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

@@ -42,7 +42,7 @@ APP_TIMEZONE=UTC
 # overrides can be made. Defaults to disabled.
 APP_THEME=false
 
-# Trusted Proxies
+# Trusted proxies
 # Used to indicate trust of systems that proxy to the application so
 # certain header values (Such as "X-Forwarded-For") can be used from the
 # incoming proxy request to provide origin detail.
@@ -58,6 +58,13 @@ DB_DATABASE=database_database
 DB_USERNAME=database_username
 DB_PASSWORD=database_user_password
 
+# MySQL specific connection options
+# Path to Certificate Authority (CA) certificate file for your MySQL instance.
+# When this option is used host name identity verification will be performed
+# which checks the hostname, used by the client, against names within the
+# certificate itself (Common Name or Subject Alternative Name).
+MYSQL_ATTR_SSL_CA="/path/to/ca.pem"
+
 # Mail system to use
 # Can be 'smtp' or 'sendmail'
 MAIL_DRIVER=smtp
@@ -73,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
@@ -136,6 +146,10 @@ STORAGE_URL=false
 # Can be 'standard', 'ldap', 'saml2' or 'oidc'
 AUTH_METHOD=standard
 
+# Automatically initiate login via external auth system if it's the only auth method.
+# Works with saml2 or oidc auth methods.
+AUTH_AUTO_INITIATE=false
+
 # Social authentication configuration
 # All disabled by default.
 # Refer to https://www.bookstackapp.com/docs/admin/third-party-auth/
@@ -216,6 +230,7 @@ LDAP_DUMP_USER_DETAILS=false
 LDAP_USER_TO_GROUPS=false
 LDAP_GROUP_ATTRIBUTE="memberOf"
 LDAP_REMOVE_FROM_GROUPS=false
+LDAP_DUMP_USER_GROUPS=false
 
 # SAML authentication configuration
 # Refer to https://www.bookstackapp.com/docs/admin/saml2-auth/
@@ -251,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
@@ -266,7 +286,7 @@ AVATAR_URL=
 # Enable diagrams.net integration
 # Can simply be true/false to enable/disable the integration.
 # Alternatively, It can be URL to the diagrams.net instance you want to use.
-# For URLs, The following URL parameters should be included: embed=1&proto=json&spin=1
+# For URLs, The following URL parameters should be included: embed=1&proto=json&spin=1&configure=1
 DRAWIO=true
 
 # Default item listing view
@@ -283,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
@@ -297,6 +317,11 @@ RECYCLE_BIN_LIFETIME=30
 # Maximum file size, in megabytes, that can be uploaded to the system.
 FILE_UPLOAD_SIZE_LIMIT=50
 
+# Export Page Size
+# Primarily used to determine page size of PDF exports.
+# Can be 'a4' or 'letter'.
+EXPORT_PAGE_SIZE=a4
+
 # Allow <script> tags in page content
 # Note, if set to 'true' the page editor may still escape scripts.
 ALLOW_CONTENT_SCRIPTS=false
@@ -319,6 +344,13 @@ ALLOW_UNTRUSTED_SERVER_FETCHING=false
 # Setting this option will also auto-adjust cookies to be SameSite=None.
 ALLOWED_IFRAME_HOSTS=null
 
+# A list of sources/hostnames that can be loaded within iframes within BookStack.
+# Space separated if multiple. BookStack host domain is auto-inferred.
+# Can be set to a lone "*" to allow all sources for iframe content (Not advised).
+# Defaults to a set of common services.
+# Current host and source for the "DRAWIO" setting will be auto-appended to the sources configured.
+ALLOWED_IFRAME_SOURCES="https://*.draw.io https://*.youtube.com https://*.youtube-nocookie.com https://*.vimeo.com"
+
 # The default and maximum item-counts for listing API requests.
 API_DEFAULT_ITEM_COUNT=100
 API_MAX_ITEM_COUNT=500
@@ -333,3 +365,11 @@ API_REQUESTS_PER_MIN=180
 # user identifier (Username or email).
 LOG_FAILED_LOGIN_MESSAGE=false
 LOG_FAILED_LOGIN_CHANNEL=errorlog_plain_webserver
+
+# Alter the precision of IP addresses stored by BookStack.
+# Should be a number between 0 and 4, where 4 retains the full IP address
+# and 0 completely hides the IP address. As an example, a value of 2 for the
+# IP address '146.191.42.4' would result in '146.191.x.x' being logged.
+# For the IPv6 address '2001:db8:85a3:8d3:1319:8a2e:370:7348' this would result as:
+# '2001:db8:85a3:8d3:x:x:x:x'
+IP_ADDRESS_PRECISION=4

.github/FUNDING.yml

@@ -1,3 +1,4 @@
 # These are supported funding model platforms
 
 github: [ssddanbrown]
+ko_fi: ssddanbrown

.github/ISSUE_TEMPLATE/api_request.yml

@@ -1,6 +1,5 @@
 name: New API Endpoint or API Ability
 description: Request a new endpoint or API feature be added
-title: "[API Request]: "
 labels: [":nut_and_bolt: API Request"]
 body:
   - type: textarea

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,6 +1,5 @@
 name: Bug Report
 description: Create a report to help us improve or fix things
-title: "[Bug Report]: "
 labels: [":bug: Bug"]
 body:
   - type: textarea
@@ -36,6 +35,15 @@ body:
       description: Provide any additional context and screenshots here to help us solve this issue
     validations:
       required: false
+  - type: input
+    id: browserdetails
+    attributes:
+      label: Browser Details
+      description: |
+        If this is an issue that occurs when using the BookStack interface, please provide details of the browser used which presents the reported issue.
+      placeholder: (eg. Firefox 97 (64-bit) on Windows 11)
+    validations:
+      required: false
   - type: input
     id: bsversion
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,9 +1,13 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Discord chat support
+  - name: Discord Chat Support
     url: https://discord.gg/ztkBqR2
-    about: Realtime support / chat with the community and the team.
+    about: Realtime support & chat with the BookStack community and the team.
 
   - name: Debugging & Common Issues
     url: https://www.bookstackapp.com/docs/admin/debugging/
-    about: Find details on how to debug issues and view common issues with thier resolutions.
+    about: Find details on how to debug issues and view common issues with their resolutions.
+
+  - name: Official Support Plans
+    url: https://www.bookstackapp.com/support/
+    about: View our official support plans that offer assured support for business.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,6 +1,5 @@
 name: Feature Request
-description: Request a new language to be added to CrowdIn for you to translate
-title: "[Feature Request]: "
+description: Request a new feature or idea to be added to BookStack
 labels: [":hammer: Feature Request"]
 body:
   - type: textarea
@@ -13,8 +12,41 @@ body:
   - type: textarea
     id: benefits
     attributes:
-      label: Describe the benefits this feature would bring to BookStack users
-      description: Explain the measurable benefits this feature would achieve for existing BookStack users
+      label: Describe the benefits this would bring to existing BookStack users
+      description: |
+        Explain the measurable benefits this feature would achieve for existing BookStack users.
+        These benefits should details outcomes in terms of what this request solves/achieves, and should not be specific to implementation.
+        This helps us understand the core desired goal so that a variety of potential implementations could be explored.
+        This field is important. Lack if input here may lead to early issue closure.
+    validations:
+      required: true
+  - type: textarea
+    id: already_achieved
+    attributes:
+      label: Can the goal of this request already be achieved via other means?
+      description: |
+        Yes/No. If yes, please describe how the requested approach fits in with the existing method.
+    validations:
+      required: true
+  - type: checkboxes
+    id: confirm-search
+    attributes:
+      label: Have you searched for an existing open/closed issue?
+      description: |
+        To help us keep these issues under control, please ensure you have first [searched our issue list](https://github.com/BookStackApp/BookStack/issues?q=is%3Aissue) for any existing issues that cover the fundemental benefit/goal of your request.
+      options:
+        - label: I have searched for existing issues and none cover my fundemental request
+          required: true
+  - type: dropdown
+    id: existing_usage
+    attributes:
+      label: How long have you been using BookStack?
+      options:
+        - Not using yet, just scoping
+        - 0 to 6 months
+        - 6 months to 1 year
+        - 1 to 5 years
+        - Over 5 years
     validations:
       required: true
   - type: textarea

.github/ISSUE_TEMPLATE/language_request.yml

@@ -1,6 +1,5 @@
 name: Language Request
-description: Request a new language to be added to CrowdIn for you to translate
-title: "[Language Request]: "
+description: Request a new language to be added to Crowdin for you to translate
 labels: [":earth_africa: Translations"]
 assignees:
   - ssddanbrown
@@ -24,7 +23,7 @@ body:
         This issue template is to request a new language be added to our [Crowdin translation management project](https://crowdin.com/project/bookstack).
         Please don't use this template to request a new language that you are not prepared to provide translations for.
       options:
-        - label: I confirm I'm offering to help translate for this new language via CrowdIn.
+        - label: I confirm I'm offering to help translate for this new language via Crowdin.
           required: true
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/support_request.yml

@@ -1,6 +1,5 @@
 name: Support Request
 description: Request support for a specific problem you have not been able to solve yourself
-title: "[Support Request]: "
 labels: [":dog2: Support"]
 body:
   - type: checkboxes

.github/translators.txt

@@ -55,6 +55,8 @@ Name :: Languages
 @Baptistou :: French
 @arcoai :: Spanish
 @Jokuna :: Korean
+@smartshogu :: German; German Informal
+@samadha56 :: Persian
 cipi1965 :: Italian
 Mykola Ronik (Mantikor) :: Ukrainian
 furkanoyk :: Turkish
@@ -136,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
@@ -158,14 +160,14 @@ HenrijsS :: Latvian
 Pascal R-B (pborgner) :: German
 Boris (Ginfred) :: Russian
 Jonas Anker Rasmussen (jonasanker) :: Danish
-Gerwin de Keijzer (gdekeijzer) :: Dutch; German; German Informal
+Gerwin de Keijzer (gdekeijzer) :: Dutch; German Informal; German
 kometchtech :: Japanese
 Auri (Atalonica) :: Catalan
 Francesco Franchina (ffranchina) :: Italian
 Aimrane Kds (aimrane.kds) :: Arabic
 whenwesober :: Indonesian
 Rem (remkovdhoef) :: Dutch
-syn7ax69 :: Bulgarian; Turkish
+syn7ax69 :: Bulgarian; Turkish; German
 Blaade :: French
 Behzad HosseinPoor (behzad.hp) :: Persian
 Ole Aldric (Swoy) :: Norwegian Bokmal
@@ -174,7 +176,7 @@ Alexander Predl (Harveyhase68) :: German
 Rem (Rem9000) :: Dutch
 Michał Stelmach (stelmach-web) :: Polish
 arniom :: French
-REMOVED_USER :: Turkish
+REMOVED_USER :: ; French; Dutch; Turkish
 林祖年 (contagion) :: Chinese Traditional
 Siamak Guodarzi (siamakgoudarzi88) :: Persian
 Lis Maestrelo (lismtrl) :: Portuguese, Brazilian
@@ -215,3 +217,106 @@ Saeed (saeed205) :: Persian
 Julesdevops :: French
 peter cerny (posli.to.semka) :: Slovak
 Pavel Karlin (pavelkarlin) :: Russian
+SmokingCrop :: Dutch
+Maciej Lebiest (Szwendacz) :: Polish
+DiscordDigital :: German; German Informal
+Gábor Marton (dodver) :: Hungarian
+Jasell :: Swedish
+Ghost_chu (ghostchu) :: Chinese Simplified
+Ravid Shachar (ravidshachar) :: Hebrew
+Helga Guchshenskaya (guchshenskaya) :: Russian
+daniel chou (chou0214) :: Chinese Traditional
+Manolis PATRIARCHE (m.patriarche) :: French
+Mohammed Haboubi (haboubi92) :: Arabic
+roncallyt :: Portuguese, Brazilian
+goegol :: Dutch
+msevgen :: Turkish
+Khroners :: French
+MASOUD HOSSEINY (masoudme) :: Persian
+Thomerson Roncally (roncallyt) :: Portuguese, Brazilian
+metaarch :: Bulgarian
+Xabi (xabikip) :: Basque
+pedromcsousa :: Portuguese
+Nir Louk (looknear) :: Hebrew
+Alex (qianmengnet) :: Chinese Simplified
+stothew :: German
+sgenc :: Turkish
+Shukrullo (vodiylik) :: Uzbek
+William W. (Nevnt) :: Chinese Traditional
+eamaro :: Portuguese
+Ypsilon-dev :: Arabic
+Hieu Vuong Trung (vuongtrunghieu) :: Vietnamese
+David Clubb (davidoclubb) :: Welsh
+welles freire (wellesximenes) :: Portuguese, Brazilian
+Magnus Jensen (MagnusHJensen) :: Danish
+Hesley Magno (hesleymagno) :: Portuguese, Brazilian
+Éric Gaspar (erga) :: French
+Fr3shlama :: German
+DSR :: Spanish, Argentina
+Andrii Bodnar (andrii-bodnar) :: Ukrainian
+Younes el Anjri (younesea28) :: Dutch
+Guclu Ozturk (gucluoz) :: Turkish
+Atmis :: French
+redjack666 :: Chinese Traditional
+Ashita007 :: Russian
+lihaorr :: Chinese Simplified
+Marcus Silber (marcus.silber82) :: German
+PellNet :: Croatian
+Winetradr :: German
+Sebastian Klaus (sebklaus) :: German
+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

@@ -0,0 +1,34 @@
+name: analyse-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
+        extensions: gd, mbstring, json, curl, xml, mysql, ldap
+
+    - name: Get Composer Cache Directory
+      id: composer-cache
+      run: |
+        echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+    - name: Cache composer packages
+      uses: actions/cache@v3
+      with:
+        path: ${{ steps.composer-cache.outputs.dir }}
+        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 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/phpstan.yml

@@ -1,41 +0,0 @@
-name: phpstan
-
-on:
-  push:
-    branches-ignore:
-      - l10n_master
-  pull_request:
-    branches-ignore:
-      - l10n_master
-
-jobs:
-  build:
-    runs-on: ubuntu-20.04
-    strategy:
-      matrix:
-        php: ['7.3']
-    steps:
-    - uses: actions/checkout@v1
-
-    - name: Setup PHP
-      uses: shivammathur/setup-php@v2
-      with:
-        php-version: ${{ matrix.php }}
-        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)"
-
-    - name: Cache composer packages
-      uses: actions/cache@v1
-      with:
-        path: ${{ steps.composer-cache.outputs.dir }}
-        key: ${{ runner.os }}-composer-${{ matrix.php }}
-
-    - 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

.github/workflows/test-migrations.yml

@@ -1,19 +1,14 @@
 name: test-migrations
 
-on:
-  push:
-    branches-ignore:
-      - l10n_master
-  pull_request:
-    branches-ignore:
-      - l10n_master
+on: [push, pull_request]
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    if: ${{ github.ref != 'refs/heads/l10n_development' }}
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
-        php: ['7.3', '7.4', '8.0', '8.1']
+        php: ['8.0', '8.1', '8.2']
     steps:
       - uses: actions/checkout@v1
 
@@ -26,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,19 +1,14 @@
-name: phpunit
+name: test-php
 
-on:
-  push:
-    branches-ignore:
-      - l10n_master
-  pull_request:
-    branches-ignore:
-      - l10n_master
+on: [push, pull_request]
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    if: ${{ github.ref != 'refs/heads/l10n_development' }}
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
-        php: ['7.3', '7.4', '8.0', '8.1']
+        php: ['8.0', '8.1', '8.2']
     steps:
     - uses: actions/checkout@v1
 
@@ -21,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: |
@@ -53,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/ActivityLogger.php

@@ -2,21 +2,15 @@
 
 namespace BookStack\Actions;
 
-use BookStack\Auth\Permissions\PermissionService;
 use BookStack\Entities\Models\Entity;
+use BookStack\Facades\Theme;
 use BookStack\Interfaces\Loggable;
+use BookStack\Theming\ThemeEvents;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Support\Facades\Log;
 
 class ActivityLogger
 {
-    protected $permissionService;
-
-    public function __construct(PermissionService $permissionService)
-    {
-        $this->permissionService = $permissionService;
-    }
-
     /**
      * Add a generic activity event to the database.
      *
@@ -35,8 +29,10 @@ class ActivityLogger
         }
 
         $activity->save();
+
         $this->setNotification($type);
         $this->dispatchWebhooks($type, $detail);
+        Theme::dispatch(ThemeEvents::ACTIVITY_LOGGED, $type, $detail);
     }
 
     /**
@@ -44,12 +40,10 @@ class ActivityLogger
      */
     protected function newActivityForUser(string $type): Activity
     {
-        $ip = request()->ip() ?? '';
-
         return (new Activity())->forceFill([
             'type'     => strtolower($type),
             'user_id'  => user()->id,
-            'ip'       => config('app.env') === 'demo' ? '127.0.0.1' : $ip,
+            'ip'       => IpFormatter::fromCurrentRequest()->format(),
         ]);
     }
 

app/Actions/ActivityQueries.php

@@ -2,7 +2,7 @@
 
 namespace BookStack\Actions;
 
-use BookStack\Auth\Permissions\PermissionService;
+use BookStack\Auth\Permissions\PermissionApplicator;
 use BookStack\Auth\User;
 use BookStack\Entities\Models\Book;
 use BookStack\Entities\Models\Chapter;
@@ -13,11 +13,11 @@ use Illuminate\Database\Eloquent\Relations\Relation;
 
 class ActivityQueries
 {
-    protected $permissionService;
+    protected PermissionApplicator $permissions;
 
-    public function __construct(PermissionService $permissionService)
+    public function __construct(PermissionApplicator $permissions)
     {
-        $this->permissionService = $permissionService;
+        $this->permissions = $permissions;
     }
 
     /**
@@ -25,8 +25,8 @@ class ActivityQueries
      */
     public function latest(int $count = 20, int $page = 0): array
     {
-        $activityList = $this->permissionService
-            ->filterRestrictedEntityRelations(Activity::query(), 'activities', 'entity_id', 'entity_type')
+        $activityList = $this->permissions
+            ->restrictEntityRelationQuery(Activity::query(), 'activities', 'entity_id', 'entity_type')
             ->orderBy('created_at', 'desc')
             ->with(['user', 'entity'])
             ->skip($count * $page)
@@ -78,8 +78,8 @@ class ActivityQueries
      */
     public function userActivity(User $user, int $count = 20, int $page = 0): array
     {
-        $activityList = $this->permissionService
-            ->filterRestrictedEntityRelations(Activity::query(), 'activities', 'entity_id', 'entity_type')
+        $activityList = $this->permissions
+            ->restrictEntityRelationQuery(Activity::query(), 'activities', 'entity_id', 'entity_type')
             ->orderBy('created_at', 'desc')
             ->where('user_id', '=', $user->id)
             ->skip($count * $page)

app/Actions/ActivityType.php

@@ -16,17 +16,22 @@ class ActivityType
     const CHAPTER_MOVE = 'chapter_move';
 
     const BOOK_CREATE = 'book_create';
+    const BOOK_CREATE_FROM_CHAPTER = 'book_create_from_chapter';
     const BOOK_UPDATE = 'book_update';
     const BOOK_DELETE = 'book_delete';
     const BOOK_SORT = 'book_sort';
 
     const BOOKSHELF_CREATE = 'bookshelf_create';
+    const BOOKSHELF_CREATE_FROM_BOOK = 'bookshelf_create_from_book';
     const BOOKSHELF_UPDATE = 'bookshelf_update';
     const BOOKSHELF_DELETE = 'bookshelf_delete';
 
     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/DispatchWebhookJob.php

@@ -3,17 +3,14 @@
 namespace BookStack\Actions;
 
 use BookStack\Auth\User;
-use BookStack\Entities\Models\Entity;
 use BookStack\Facades\Theme;
 use BookStack\Interfaces\Loggable;
-use BookStack\Model;
 use BookStack\Theming\ThemeEvents;
 use Illuminate\Bus\Queueable;
 use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Foundation\Bus\Dispatchable;
 use Illuminate\Queue\InteractsWithQueue;
 use Illuminate\Queue\SerializesModels;
-use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Log;
 
@@ -24,31 +21,16 @@ class DispatchWebhookJob implements ShouldQueue
     use Queueable;
     use SerializesModels;
 
-    /**
-     * @var Webhook
-     */
-    protected $webhook;
-
-    /**
-     * @var string
-     */
-    protected $event;
+    protected Webhook $webhook;
+    protected string $event;
+    protected User $initiator;
+    protected int $initiatedTime;
 
     /**
      * @var string|Loggable
      */
     protected $detail;
 
-    /**
-     * @var User
-     */
-    protected $initiator;
-
-    /**
-     * @var int
-     */
-    protected $initiatedTime;
-
     /**
      * Create a new job instance.
      *
@@ -70,8 +52,8 @@ class DispatchWebhookJob implements ShouldQueue
      */
     public function handle()
     {
-        $themeResponse = Theme::dispatch(ThemeEvents::WEBHOOK_CALL_BEFORE, $this->event, $this->webhook, $this->detail);
-        $webhookData = $themeResponse ?? $this->buildWebhookData();
+        $themeResponse = Theme::dispatch(ThemeEvents::WEBHOOK_CALL_BEFORE, $this->event, $this->webhook, $this->detail, $this->initiator, $this->initiatedTime);
+        $webhookData = $themeResponse ?? WebhookFormatter::getDefault($this->event, $this->webhook, $this->detail, $this->initiator, $this->initiatedTime)->format();
         $lastError = null;
 
         try {
@@ -97,36 +79,4 @@ class DispatchWebhookJob implements ShouldQueue
 
         $this->webhook->save();
     }
-
-    protected function buildWebhookData(): array
-    {
-        $textParts = [
-            $this->initiator->name,
-            trans('activities.' . $this->event),
-        ];
-
-        if ($this->detail instanceof Entity) {
-            $textParts[] = '"' . $this->detail->name . '"';
-        }
-
-        $data = [
-            'event'                    => $this->event,
-            'text'                     => implode(' ', $textParts),
-            'triggered_at'             => Carbon::createFromTimestampUTC($this->initiatedTime)->toISOString(),
-            'triggered_by'             => $this->initiator->attributesToArray(),
-            'triggered_by_profile_url' => $this->initiator->getProfileUrl(),
-            'webhook_id'               => $this->webhook->id,
-            'webhook_name'             => $this->webhook->name,
-        ];
-
-        if (method_exists($this->detail, 'getUrl')) {
-            $data['url'] = $this->detail->getUrl();
-        }
-
-        if ($this->detail instanceof Model) {
-            $data['related_item'] = $this->detail->attributesToArray();
-        }
-
-        return $data;
-    }
 }

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/IpFormatter.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace BookStack\Actions;
+
+class IpFormatter
+{
+    protected string $ip;
+    protected int $precision;
+
+    public function __construct(string $ip, int $precision)
+    {
+        $this->ip = trim($ip);
+        $this->precision = max(0, min($precision, 4));
+    }
+
+    public function format(): string
+    {
+        if (empty($this->ip) || $this->precision === 4) {
+            return $this->ip;
+        }
+
+        return $this->isIpv6() ? $this->maskIpv6() : $this->maskIpv4();
+    }
+
+    protected function maskIpv4(): string
+    {
+        $exploded = $this->explodeAndExpandIp('.', 4);
+        $maskGroupCount = min(4 - $this->precision, count($exploded));
+
+        for ($i = 0; $i < $maskGroupCount; $i++) {
+            $exploded[3 - $i] = 'x';
+        }
+
+        return implode('.', $exploded);
+    }
+
+    protected function maskIpv6(): string
+    {
+        $exploded = $this->explodeAndExpandIp(':', 8);
+        $maskGroupCount = min(8 - ($this->precision * 2), count($exploded));
+
+        for ($i = 0; $i < $maskGroupCount; $i++) {
+            $exploded[7 - $i] = 'x';
+        }
+
+        return implode(':', $exploded);
+    }
+
+    protected function isIpv6(): bool
+    {
+        return strpos($this->ip, ':') !== false;
+    }
+
+    protected function explodeAndExpandIp(string $separator, int $targetLength): array
+    {
+        $exploded = explode($separator, $this->ip);
+
+        while (count($exploded) < $targetLength) {
+            $emptyIndex = array_search('', $exploded) ?: count($exploded) - 1;
+            array_splice($exploded, $emptyIndex, 0, '0');
+        }
+
+        $emptyIndex = array_search('', $exploded);
+        if ($emptyIndex !== false) {
+            $exploded[$emptyIndex] = '0';
+        }
+
+        return $exploded;
+    }
+
+    public static function fromCurrentRequest(): self
+    {
+        $ip = request()->ip() ?? '';
+
+        if (config('app.env') === 'demo') {
+            $ip = '127.0.0.1';
+        }
+
+        return new self($ip, config('app.ip_address_precision'));
+    }
+}

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/TagClassGenerator.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace BookStack\Actions;
+
+class TagClassGenerator
+{
+    protected array $tags;
+
+    /**
+     * @param Tag[] $tags
+     */
+    public function __construct(array $tags)
+    {
+        $this->tags = $tags;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function generate(): array
+    {
+        $classes = [];
+
+        foreach ($this->tags as $tag) {
+            $name = $this->normalizeTagClassString($tag->name);
+            $value = $this->normalizeTagClassString($tag->value);
+            $classes[] = 'tag-name-' . $name;
+            if ($value) {
+                $classes[] = 'tag-value-' . $value;
+                $classes[] = 'tag-pair-' . $name . '-' . $value;
+            }
+        }
+
+        return array_unique($classes);
+    }
+
+    public function generateAsString(): string
+    {
+        return implode(' ', $this->generate());
+    }
+
+    protected function normalizeTagClassString(string $value): string
+    {
+        $value = str_replace(' ', '', strtolower($value));
+        $value = str_replace('-', '', strtolower($value));
+
+        return $value;
+    }
+}

app/Actions/TagRepo.php

@@ -2,38 +2,42 @@
 
 namespace BookStack\Actions;
 
-use BookStack\Auth\Permissions\PermissionService;
+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 $tag;
-    protected $permissionService;
-
-    public function __construct(PermissionService $ps)
-    {
-        $this->permissionService = $ps;
+    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',
                 ($searchTerm || $nameFilter) ? 'value' : DB::raw('COUNT(distinct value) as `values`'),
                 DB::raw('COUNT(id) as usages'),
-                DB::raw('SUM(IF(entity_type = \'BookStack\\\\Page\', 1, 0)) as page_count'),
-                DB::raw('SUM(IF(entity_type = \'BookStack\\\\Chapter\', 1, 0)) as chapter_count'),
-                DB::raw('SUM(IF(entity_type = \'BookStack\\\\Book\', 1, 0)) as book_count'),
-                DB::raw('SUM(IF(entity_type = \'BookStack\\\\BookShelf\', 1, 0)) as shelf_count'),
+                DB::raw('SUM(IF(entity_type = \'page\', 1, 0)) as page_count'),
+                DB::raw('SUM(IF(entity_type = \'chapter\', 1, 0)) as chapter_count'),
+                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);
@@ -51,28 +55,28 @@ class TagRepo
             });
         }
 
-        return $this->permissionService->filterRestrictedEntityRelations($query, 'tags', 'entity_id', 'entity_type');
+        return $this->permissions->restrictEntityRelationQuery($query, 'tags', 'entity_id', 'entity_type');
     }
 
     /**
      * 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->permissionService->filterRestrictedEntityRelations($query, 'tags', 'entity_id', 'entity_type');
+        $query = $this->permissions->restrictEntityRelationQuery($query, 'tags', 'entity_id', 'entity_type');
 
-        return $query->get(['name'])->pluck('name');
+        return $query->pluck('name');
     }
 
     /**
@@ -80,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) {
@@ -96,9 +101,9 @@ class TagRepo
             $query = $query->where('name', '=', $tagName);
         }
 
-        $query = $this->permissionService->filterRestrictedEntityRelations($query, 'tags', 'entity_id', 'entity_type');
+        $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/WebhookFormatter.php

@@ -0,0 +1,124 @@
+<?php
+
+namespace BookStack\Actions;
+
+use BookStack\Auth\User;
+use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\Page;
+use BookStack\Interfaces\Loggable;
+use BookStack\Model;
+use Illuminate\Support\Carbon;
+
+class WebhookFormatter
+{
+    protected Webhook $webhook;
+    protected string $event;
+    protected User $initiator;
+    protected int $initiatedTime;
+
+    /**
+     * @var string|Loggable
+     */
+    protected $detail;
+
+    /**
+     * @var array{condition: callable(string, Model):bool, format: callable(Model):void}[]
+     */
+    protected $modelFormatters = [];
+
+    public function __construct(string $event, Webhook $webhook, $detail, User $initiator, int $initiatedTime)
+    {
+        $this->webhook = $webhook;
+        $this->event = $event;
+        $this->initiator = $initiator;
+        $this->initiatedTime = $initiatedTime;
+        $this->detail = is_object($detail) ? clone $detail : $detail;
+    }
+
+    public function format(): array
+    {
+        $data = [
+            'event'                    => $this->event,
+            'text'                     => $this->formatText(),
+            'triggered_at'             => Carbon::createFromTimestampUTC($this->initiatedTime)->toISOString(),
+            'triggered_by'             => $this->initiator->attributesToArray(),
+            'triggered_by_profile_url' => $this->initiator->getProfileUrl(),
+            'webhook_id'               => $this->webhook->id,
+            'webhook_name'             => $this->webhook->name,
+        ];
+
+        if (method_exists($this->detail, 'getUrl')) {
+            $data['url'] = $this->detail->getUrl();
+        }
+
+        if ($this->detail instanceof Model) {
+            $data['related_item'] = $this->formatModel();
+        }
+
+        return $data;
+    }
+
+    /**
+     * @param callable(string, Model):bool $condition
+     * @param callable(Model):void         $format
+     */
+    public function addModelFormatter(callable $condition, callable $format): void
+    {
+        $this->modelFormatters[] = [
+            'condition' => $condition,
+            'format'    => $format,
+        ];
+    }
+
+    public function addDefaultModelFormatters(): void
+    {
+        // Load entity owner, creator, updater details
+        $this->addModelFormatter(
+            fn ($event, $model) => ($model instanceof Entity),
+            fn ($model) => $model->load(['ownedBy', 'createdBy', 'updatedBy'])
+        );
+
+        // Load revision detail for page update and create events
+        $this->addModelFormatter(
+            fn ($event, $model) => ($model instanceof Page && ($event === ActivityType::PAGE_CREATE || $event === ActivityType::PAGE_UPDATE)),
+            fn ($model) => $model->load('currentRevision')
+        );
+    }
+
+    protected function formatModel(): array
+    {
+        /** @var Model $model */
+        $model = $this->detail;
+        $model->unsetRelations();
+
+        foreach ($this->modelFormatters as $formatter) {
+            if ($formatter['condition']($this->event, $model)) {
+                $formatter['format']($model);
+            }
+        }
+
+        return $model->toArray();
+    }
+
+    protected function formatText(): string
+    {
+        $textParts = [
+            $this->initiator->name,
+            trans('activities.' . $this->event),
+        ];
+
+        if ($this->detail instanceof Entity) {
+            $textParts[] = '"' . $this->detail->name . '"';
+        }
+
+        return implode(' ', $textParts);
+    }
+
+    public static function getDefault(string $event, Webhook $webhook, $detail, User $initiator, int $initiatedTime): self
+    {
+        $instance = new self($event, $webhook, $detail, $initiator, $initiatedTime);
+        $instance->addDefaultModelFormatters();
+
+        return $instance;
+    }
+}

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/ApiDocsGenerator.php

@@ -3,11 +3,13 @@
 namespace BookStack\Api;
 
 use BookStack\Http\Controllers\Api\ApiController;
+use Exception;
 use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\Str;
+use Illuminate\Validation\Rules\Password;
 use ReflectionClass;
 use ReflectionException;
 use ReflectionMethod;
@@ -100,11 +102,37 @@ class ApiDocsGenerator
             $this->controllerClasses[$className] = $class;
         }
 
-        $rules = $class->getValdationRules()[$methodName] ?? [];
+        $rules = collect($class->getValidationRules()[$methodName] ?? [])->map(function ($validations) {
+            return array_map(function ($validation) {
+                return $this->getValidationAsString($validation);
+            }, $validations);
+        })->toArray();
 
         return empty($rules) ? null : $rules;
     }
 
+    /**
+     * Convert the given validation message to a readable string.
+     */
+    protected function getValidationAsString($validation): string
+    {
+        if (is_string($validation)) {
+            return $validation;
+        }
+
+        if (is_object($validation) && method_exists($validation, '__toString')) {
+            return strval($validation);
+        }
+
+        if ($validation instanceof Password) {
+            return 'min:8';
+        }
+
+        $class = get_class($validation);
+
+        throw new Exception("Cannot provide string representation of rule for class: {$class}");
+    }
+
     /**
      * Parse out the description text from a class method comment.
      */

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

@@ -4,15 +4,29 @@ namespace BookStack\Api;
 
 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;
 
-    protected $filterOperators = [
+    /**
+     * @var string[]
+     */
+    protected array $fields;
+
+    /**
+     * @var array<callable>
+     */
+    protected array $resultModifiers = [];
+
+    /**
+     * @var array<string, string>
+     */
+    protected array $filterOperators = [
         'eq'   => '=',
         'ne'   => '!=',
         'gt'   => '>',
@@ -24,6 +38,7 @@ class ListingResponseBuilder
 
     /**
      * ListingResponseBuilder constructor.
+     * The given fields will be forced visible within the model results.
      */
     public function __construct(Builder $query, Request $request, array $fields)
     {
@@ -35,12 +50,16 @@ class ListingResponseBuilder
     /**
      * Get the response from this builder.
      */
-    public function toResponse()
+    public function toResponse(): JsonResponse
     {
         $filteredQuery = $this->filterQuery($this->query);
 
         $total = $filteredQuery->count();
-        $data = $this->fetchData($filteredQuery);
+        $data = $this->fetchData($filteredQuery)->each(function ($model) {
+            foreach ($this->resultModifiers as $modifier) {
+                $modifier($model);
+            }
+        });
 
         return response()->json([
             'data'  => $data,
@@ -49,7 +68,17 @@ class ListingResponseBuilder
     }
 
     /**
-     * Fetch the data to return in the response.
+     * Add a callback to modify each element of the results.
+     *
+     * @param (callable(Model): void) $modifier
+     */
+    public function modifyResults(callable $modifier): void
+    {
+        $this->resultModifiers[] = $modifier;
+    }
+
+    /**
+     * Fetch the data to return within the response.
      */
     protected function fetchData(Builder $query): Collection
     {

app/Auth/Access/GroupSyncService.php

@@ -28,10 +28,8 @@ class GroupSyncService
      */
     protected function externalIdMatchesGroupNames(string $externalId, array $groupNames): bool
     {
-        $externalAuthIds = explode(',', strtolower($externalId));
-
-        foreach ($externalAuthIds as $externalAuthId) {
-            if (in_array(trim($externalAuthId), $groupNames)) {
+        foreach ($this->parseRoleExternalAuthId($externalId) as $externalAuthId) {
+            if (in_array($externalAuthId, $groupNames)) {
                 return true;
             }
         }
@@ -39,6 +37,18 @@ class GroupSyncService
         return false;
     }
 
+    protected function parseRoleExternalAuthId(string $externalId): array
+    {
+        $inputIds = preg_split('/(?<!\\\),/', strtolower($externalId));
+        $cleanIds = [];
+
+        foreach ($inputIds as $inputId) {
+            $cleanIds[] = str_replace('\,', ',', trim($inputId));
+        }
+
+        return $cleanIds;
+    }
+
     /**
      * Match an array of group names to BookStack system roles.
      * Formats group names to be lower-case and hyphenated.

app/Auth/Access/Guards/LdapSessionGuard.php

@@ -5,6 +5,7 @@ namespace BookStack\Auth\Access\Guards;
 use BookStack\Auth\Access\LdapService;
 use BookStack\Auth\Access\RegistrationService;
 use BookStack\Auth\User;
+use BookStack\Exceptions\JsonDebugException;
 use BookStack\Exceptions\LdapException;
 use BookStack\Exceptions\LoginAttemptEmailNeededException;
 use BookStack\Exceptions\LoginAttemptException;
@@ -15,7 +16,7 @@ use Illuminate\Support\Str;
 
 class LdapSessionGuard extends ExternalBaseSessionGuard
 {
-    protected $ldapService;
+    protected LdapService $ldapService;
 
     /**
      * LdapSessionGuard constructor.
@@ -59,8 +60,9 @@ class LdapSessionGuard extends ExternalBaseSessionGuard
      * @param array $credentials
      * @param bool  $remember
      *
+     * @throws LdapException*@throws \BookStack\Exceptions\JsonDebugException
      * @throws LoginAttemptException
-     * @throws LdapException
+     * @throws JsonDebugException
      *
      * @return bool
      */
@@ -84,7 +86,7 @@ class LdapSessionGuard extends ExternalBaseSessionGuard
             try {
                 $user = $this->createNewFromLdapAndCreds($userDetails, $credentials);
             } catch (UserRegistrationException $exception) {
-                throw new LoginAttemptException($exception->message);
+                throw new LoginAttemptException($exception->getMessage());
             }
         }
 

app/Auth/Access/LdapService.php

@@ -15,12 +15,17 @@ use Illuminate\Support\Facades\Log;
  */
 class LdapService
 {
-    protected $ldap;
-    protected $groupSyncService;
+    protected Ldap $ldap;
+    protected GroupSyncService $groupSyncService;
+    protected UserAvatars $userAvatars;
+
+    /**
+     * @var resource
+     */
     protected $ldapConnection;
-    protected $userAvatars;
-    protected $config;
-    protected $enabled;
+
+    protected array $config;
+    protected bool $enabled;
 
     /**
      * LdapService constructor.
@@ -100,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']) {
@@ -274,6 +279,7 @@ class LdapService
      * Get the groups a user is a part of on ldap.
      *
      * @throws LdapException
+     * @throws JsonDebugException
      */
     public function getUserGroups(string $userName): array
     {
@@ -285,8 +291,17 @@ class LdapService
         }
 
         $userGroups = $this->groupFilter($user);
+        $allGroups = $this->getGroupsRecursive($userGroups, []);
 
-        return $this->getGroupsRecursive($userGroups, []);
+        if ($this->config['dump_user_groups']) {
+            throw new JsonDebugException([
+                'details_from_ldap'             => $user,
+                'parsed_direct_user_groups'     => $userGroups,
+                'parsed_recursive_user_groups'  => $allGroups,
+            ]);
+        }
+
+        return $allGroups;
     }
 
     /**
@@ -369,6 +384,7 @@ class LdapService
      * Sync the LDAP groups to the user roles for the current user.
      *
      * @throws LdapException
+     * @throws JsonDebugException
      */
     public function syncGroups(User $user, string $username)
     {

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/OidcException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace BookStack\Auth\Access\Oidc;
+
+use Exception;
+
+class OidcException extends Exception
+{
+}

app/Auth/Access/Oidc/OidcIssuerDiscoveryException.php

@@ -2,6 +2,8 @@
 
 namespace BookStack\Auth\Access\Oidc;
 
-class OidcIssuerDiscoveryException extends \Exception
+use Exception;
+
+class OidcIssuerDiscoveryException extends Exception
 {
 }

app/Auth/Access/Oidc/OidcJwtSigningKey.php

@@ -60,15 +60,17 @@ class OidcJwtSigningKey
      */
     protected function loadFromJwkArray(array $jwk)
     {
-        if ($jwk['alg'] !== 'RS256') {
-            throw new OidcInvalidKeyException("Only RS256 keys are currently supported. Found key using {$jwk['alg']}");
+        // 'alg' is optional for a JWK, but we will still attempt to validate if
+        // it exists otherwise presume it will be compatible.
+        $alg = $jwk['alg'] ?? null;
+        if ($jwk['kty'] !== 'RSA' || !(is_null($alg) || $alg === 'RS256')) {
+            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,7 +141,10 @@ class OidcProviderSettings
     protected function filterKeys(array $keys): array
     {
         return array_filter($keys, function (array $key) {
-            return $key['kty'] === 'RSA' && $key['use'] === 'sig' && $key['alg'] === 'RS256';
+            $alg = $key['alg'] ?? 'RS256';
+            $use = $key['use'] ?? 'sig';
+
+            return $key['kty'] === 'RSA' && $use === 'sig' && $alg === 'RS256';
         });
     }
 

app/Auth/Access/Oidc/OidcService.php

@@ -2,22 +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\OpenIdConnectException;
 use BookStack\Exceptions\StoppedAuthenticationException;
 use BookStack\Exceptions\UserRegistrationException;
-use function config;
-use Exception;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Cache;
 use League\OAuth2\Client\OptionProvider\HttpBasicAuthOptionProvider;
-use Psr\Http\Client\ClientExceptionInterface;
+use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
 use Psr\Http\Client\ClientInterface as HttpClient;
-use function trans;
-use function url;
 
 /**
  * Class OpenIdConnectService
@@ -25,30 +21,37 @@ use function url;
  */
 class OidcService
 {
-    protected $registrationService;
-    protected $loginService;
-    protected $httpClient;
+    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;
     }
 
     /**
      * Initiate an authorization flow.
      *
+     * @throws OidcException
+     *
      * @return array{url: string, state: string}
      */
     public function login(): array
     {
         $settings = $this->getProviderSettings();
         $provider = $this->getProvider($settings);
-
         return [
             'url'   => $provider->getAuthorizationUrl(),
             'state' => $provider->getState(),
@@ -57,14 +60,15 @@ class OidcService
 
     /**
      * Process the Authorization response from the authorization server and
-     * return the matching, or new if registration active, user matched to
-     * the authorization server.
-     * Returns null if not authenticated.
+     * return the matching, or new if registration active, user matched to the
+     * authorization server. Throws if the user cannot be auth if not authenticated.
      *
-     * @throws Exception
-     * @throws ClientExceptionInterface
+     * @throws JsonDebugException
+     * @throws OidcException
+     * @throws StoppedAuthenticationException
+     * @throws IdentityProviderException
      */
-    public function processAuthorizeResponse(?string $authorizationCode): ?User
+    public function processAuthorizeResponse(?string $authorizationCode): User
     {
         $settings = $this->getProviderSettings();
         $provider = $this->getProvider($settings);
@@ -78,8 +82,7 @@ class OidcService
     }
 
     /**
-     * @throws OidcIssuerDiscoveryException
-     * @throws ClientExceptionInterface
+     * @throws OidcException
      */
     protected function getProviderSettings(): OidcProviderSettings
     {
@@ -100,7 +103,11 @@ class OidcService
 
         // Run discovery
         if ($config['discover'] ?? false) {
-            $settings->discoverFromIssuer($this->httpClient, Cache::store(null), 15);
+            try {
+                $settings->discoverFromIssuer($this->httpClient, Cache::store(null), 15);
+            } catch (OidcIssuerDiscoveryException $exception) {
+                throw new OidcException('OIDC Discovery Error: ' . $exception->getMessage());
+            }
         }
 
         $settings->validate();
@@ -113,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);
     }
 
     /**
@@ -141,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),
         ];
     }
 
@@ -161,9 +213,8 @@ class OidcService
      * Processes a received access token for a user. Login the user when
      * they exist, optionally registering them automatically.
      *
-     * @throws OpenIdConnectException
+     * @throws OidcException
      * @throws JsonDebugException
-     * @throws UserRegistrationException
      * @throws StoppedAuthenticationException
      */
     protected function processAccessTokenCallback(OidcAccessToken $accessToken, OidcProviderSettings $settings): User
@@ -182,28 +233,34 @@ class OidcService
         try {
             $idToken->validate($settings->clientId);
         } catch (OidcInvalidTokenException $exception) {
-            throw new OpenIdConnectException("ID token validate failed with error: {$exception->getMessage()}");
+            throw new OidcException("ID token validate failed with error: {$exception->getMessage()}");
         }
 
         $userDetails = $this->getUserDetails($idToken);
         $isLoggedIn = auth()->check();
 
         if (empty($userDetails['email'])) {
-            throw new OpenIdConnectException(trans('errors.oidc_no_email_address'));
+            throw new OidcException(trans('errors.oidc_no_email_address'));
         }
 
         if ($isLoggedIn) {
-            throw new OpenIdConnectException(trans('errors.oidc_already_logged_in'), '/login');
+            throw new OidcException(trans('errors.oidc_already_logged_in'));
         }
 
-        $user = $this->registrationService->findOrRegister(
-            $userDetails['name'],
-            $userDetails['email'],
-            $userDetails['external_id']
-        );
+        try {
+            $user = $this->registrationService->findOrRegister(
+                $userDetails['name'],
+                $userDetails['email'],
+                $userDetails['external_id']
+            );
+        } catch (UserRegistrationException $exception) {
+            throw new OidcException($exception->getMessage());
+        }
 
-        if ($user === null) {
-            throw new OpenIdConnectException(trans('errors.oidc_user_not_registered', ['name' => $userDetails['external_id']]), '/login');
+        if ($this->shouldSyncGroups()) {
+            $groups = $userDetails['groups'];
+            $detachExisting = $this->config()['remove_from_groups'];
+            $this->groupService->syncUserWithFoundGroups($user, $groups, $detachExisting);
         }
 
         $this->loginService->login($user, 'oidc');
@@ -218,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/RegistrationService.php

@@ -96,7 +96,8 @@ class RegistrationService
         }
 
         // Create the user
-        $newUser = $this->userRepo->registerNew($userData, $emailConfirmed);
+        $newUser = $this->userRepo->createWithoutActivity($userData, $emailConfirmed);
+        $newUser->attachDefaultRole();
 
         // Assign social account if given
         if ($socialAccount) {

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

@@ -0,0 +1,292 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+use BookStack\Auth\Role;
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\BookChild;
+use BookStack\Entities\Models\Bookshelf;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\Page;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Joint permissions provide a pre-query "cached" table of view permissions for all core entity
+ * types for all roles in the system. This class generates out that table for different scenarios.
+ */
+class JointPermissionBuilder
+{
+    /**
+     * Re-generate all entity permission from scratch.
+     */
+    public function rebuildForAll()
+    {
+        JointPermission::query()->truncate();
+
+        // Get all roles (Should be the most limited dimension)
+        $roles = Role::query()->with('permissions')->get()->all();
+
+        // Chunk through all books
+        $this->bookFetchQuery()->chunk(5, function (EloquentCollection $books) use ($roles) {
+            $this->buildJointPermissionsForBooks($books, $roles);
+        });
+
+        // Chunk through all bookshelves
+        Bookshelf::query()->withTrashed()->select(['id', 'owned_by'])
+            ->chunk(50, function (EloquentCollection $shelves) use ($roles) {
+                $this->createManyJointPermissions($shelves->all(), $roles);
+            });
+    }
+
+    /**
+     * Rebuild the entity jointPermissions for a particular entity.
+     */
+    public function rebuildForEntity(Entity $entity)
+    {
+        $entities = [$entity];
+        if ($entity instanceof Book) {
+            $books = $this->bookFetchQuery()->where('id', '=', $entity->id)->get();
+            $this->buildJointPermissionsForBooks($books, Role::query()->with('permissions')->get()->all(), true);
+
+            return;
+        }
+
+        /** @var BookChild $entity */
+        if ($entity->book) {
+            $entities[] = $entity->book;
+        }
+
+        if ($entity instanceof Page && $entity->chapter_id) {
+            $entities[] = $entity->chapter;
+        }
+
+        if ($entity instanceof Chapter) {
+            foreach ($entity->pages as $page) {
+                $entities[] = $page;
+            }
+        }
+
+        $this->buildJointPermissionsForEntities($entities);
+    }
+
+    /**
+     * Build the entity jointPermissions for a particular role.
+     */
+    public function rebuildForRole(Role $role)
+    {
+        $roles = [$role];
+        $role->jointPermissions()->delete();
+        $role->load('permissions');
+
+        // Chunk through all books
+        $this->bookFetchQuery()->chunk(20, function ($books) use ($roles) {
+            $this->buildJointPermissionsForBooks($books, $roles);
+        });
+
+        // Chunk through all bookshelves
+        Bookshelf::query()->select(['id', 'owned_by'])
+            ->chunk(50, function ($shelves) use ($roles) {
+                $this->createManyJointPermissions($shelves->all(), $roles);
+            });
+    }
+
+    /**
+     * Get a query for fetching a book with its children.
+     */
+    protected function bookFetchQuery(): Builder
+    {
+        return Book::query()->withTrashed()
+            ->select(['id', 'owned_by'])->with([
+                'chapters' => function ($query) {
+                    $query->withTrashed()->select(['id', 'owned_by', 'book_id']);
+                },
+                'pages' => function ($query) {
+                    $query->withTrashed()->select(['id', 'owned_by', 'book_id', 'chapter_id']);
+                },
+            ]);
+    }
+
+    /**
+     * Build joint permissions for the given book and role combinations.
+     */
+    protected function buildJointPermissionsForBooks(EloquentCollection $books, array $roles, bool $deleteOld = false)
+    {
+        $entities = clone $books;
+
+        /** @var Book $book */
+        foreach ($books->all() as $book) {
+            foreach ($book->getRelation('chapters') as $chapter) {
+                $entities->push($chapter);
+            }
+            foreach ($book->getRelation('pages') as $page) {
+                $entities->push($page);
+            }
+        }
+
+        if ($deleteOld) {
+            $this->deleteManyJointPermissionsForEntities($entities->all());
+        }
+
+        $this->createManyJointPermissions($entities->all(), $roles);
+    }
+
+    /**
+     * Rebuild the entity jointPermissions for a collection of entities.
+     */
+    protected function buildJointPermissionsForEntities(array $entities)
+    {
+        $roles = Role::query()->get()->values()->all();
+        $this->deleteManyJointPermissionsForEntities($entities);
+        $this->createManyJointPermissions($entities, $roles);
+    }
+
+    /**
+     * Delete all the entity jointPermissions for a list of entities.
+     *
+     * @param Entity[] $entities
+     */
+    protected function deleteManyJointPermissionsForEntities(array $entities)
+    {
+        $simpleEntities = $this->entitiesToSimpleEntities($entities);
+        $idsByType = $this->entitiesToTypeIdMap($simpleEntities);
+
+        DB::transaction(function () use ($idsByType) {
+            foreach ($idsByType as $type => $ids) {
+                foreach (array_chunk($ids, 1000) as $idChunk) {
+                    DB::table('joint_permissions')
+                        ->where('entity_type', '=', $type)
+                        ->whereIn('entity_id', $idChunk)
+                        ->delete();
+                }
+            }
+        });
+    }
+
+    /**
+     * @param Entity[] $entities
+     *
+     * @return SimpleEntityData[]
+     */
+    protected function entitiesToSimpleEntities(array $entities): array
+    {
+        $simpleEntities = [];
+
+        foreach ($entities as $entity) {
+            $simple = SimpleEntityData::fromEntity($entity);
+            $simpleEntities[] = $simple;
+        }
+
+        return $simpleEntities;
+    }
+
+    /**
+     * Create & Save entity jointPermissions for many entities and roles.
+     *
+     * @param Entity[] $originalEntities
+     * @param Role[]   $roles
+     */
+    protected function createManyJointPermissions(array $originalEntities, array $roles)
+    {
+        $entities = $this->entitiesToSimpleEntities($originalEntities);
+        $jointPermissions = [];
+
+        // Fetch related entity permissions
+        $permissions = new MassEntityPermissionEvaluator($entities, 'view');
+
+        // Create a mapping of role permissions
+        $rolePermissionMap = [];
+        foreach ($roles as $role) {
+            foreach ($role->permissions as $permission) {
+                $rolePermissionMap[$role->getRawAttribute('id') . ':' . $permission->getRawAttribute('name')] = true;
+            }
+        }
+
+        // Create Joint Permission Data
+        foreach ($entities as $entity) {
+            foreach ($roles as $role) {
+                $jp = $this->createJointPermissionData(
+                    $entity,
+                    $role->getRawAttribute('id'),
+                    $permissions,
+                    $rolePermissionMap,
+                    $role->system_name === 'admin'
+                );
+                $jointPermissions[] = $jp;
+            }
+        }
+
+        DB::transaction(function () use ($jointPermissions) {
+            foreach (array_chunk($jointPermissions, 1000) as $jointPermissionChunk) {
+                DB::table('joint_permissions')->insert($jointPermissionChunk);
+            }
+        });
+    }
+
+    /**
+     * From the given entity list, provide back a mapping of entity types to
+     * the ids of that given type. The type used is the DB morph class.
+     *
+     * @param SimpleEntityData[] $entities
+     *
+     * @return array<string, int[]>
+     */
+    protected function entitiesToTypeIdMap(array $entities): array
+    {
+        $idsByType = [];
+
+        foreach ($entities as $entity) {
+            if (!isset($idsByType[$entity->type])) {
+                $idsByType[$entity->type] = [];
+            }
+
+            $idsByType[$entity->type][] = $entity->id;
+        }
+
+        return $idsByType;
+    }
+
+    /**
+     * Create entity permission data for an entity and role
+     * for a particular action.
+     */
+    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']);
+        $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, int $permissionStatus, bool $hasPermissionOwn): array
+    {
+        $ownPermissionActive = ($hasPermissionOwn && $permissionStatus !== PermissionStatus::EXPLICIT_DENY && $entity->owned_by);
+
+        return [
+            '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

@@ -0,0 +1,203 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+use BookStack\Auth\Role;
+use BookStack\Auth\User;
+use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\Page;
+use BookStack\Model;
+use BookStack\Traits\HasCreatorAndUpdater;
+use BookStack\Traits\HasOwner;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Query\Builder as QueryBuilder;
+use InvalidArgumentException;
+
+class PermissionApplicator
+{
+    /**
+     * Checks if an entity has a restriction set upon it.
+     *
+     * @param HasCreatorAndUpdater|HasOwner $ownable
+     */
+    public function checkOwnableUserAccess(Model $ownable, string $permission): bool
+    {
+        $explodedPermission = explode('-', $permission);
+        $action = $explodedPermission[1] ?? $explodedPermission[0];
+        $fullPermission = count($explodedPermission) > 1 ? $permission : $ownable->getMorphClass() . '-' . $permission;
+
+        $user = $this->currentUser();
+        $userRoleIds = $this->getCurrentUserRoleIds();
+
+        $allRolePermission = $user->can($fullPermission . '-all');
+        $ownRolePermission = $user->can($fullPermission . '-own');
+        $nonJointPermissions = ['restrictions', 'image', 'attachment', 'comment'];
+        $ownerField = ($ownable instanceof Entity) ? 'owned_by' : 'created_by';
+        $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
+        if (in_array($explodedPermission[0], $nonJointPermissions)) {
+            return $hasRolePermission;
+        }
+
+        $hasApplicableEntityPermissions = $this->hasEntityPermission($ownable, $userRoleIds, $action);
+
+        return is_null($hasApplicableEntityPermissions) ? $hasRolePermission : $hasApplicableEntityPermissions;
+    }
+
+    /**
+     * Check if there are permissions that are applicable for the given entity item, action and roles.
+     * Returns null when no entity permissions are in force.
+     */
+    protected function hasEntityPermission(Entity $entity, array $userRoleIds, string $action): ?bool
+    {
+        $this->ensureValidEntityAction($action);
+
+        return (new EntityPermissionEvaluator($action))->evaluateEntityForUser($entity, $userRoleIds);
+    }
+
+    /**
+     * Checks if a user has the given permission for any items in the system.
+     * Can be passed an entity instance to filter on a specific type.
+     */
+    public function checkUserHasEntityPermissionOnAny(string $action, string $entityClass = ''): bool
+    {
+        $this->ensureValidEntityAction($action);
+
+        $permissionQuery = EntityPermission::query()
+            ->where($action, '=', true)
+            ->whereIn('role_id', $this->getCurrentUserRoleIds());
+
+        if (!empty($entityClass)) {
+            /** @var Entity $entityInstance */
+            $entityInstance = app()->make($entityClass);
+            $permissionQuery = $permissionQuery->where('entity_type', '=', $entityInstance->getMorphClass());
+        }
+
+        $hasPermission = $permissionQuery->count() > 0;
+
+        return $hasPermission;
+    }
+
+    /**
+     * Limit the given entity query so that the query will only
+     * return items that the user has view permission for.
+     */
+    public function restrictEntityQuery(Builder $query): Builder
+    {
+        return $query->where(function (Builder $parentQuery) {
+            $parentQuery->whereHas('jointPermissions', function (Builder $permissionQuery) {
+                $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]);
+            });
+        });
+    }
+
+    /**
+     * Extend the given page query to ensure draft items are not visible
+     * unless created by the given user.
+     */
+    public function restrictDraftsOnPageQuery(Builder $query): Builder
+    {
+        return $query->where(function (Builder $query) {
+            $query->where('draft', '=', false)
+                ->orWhere(function (Builder $query) {
+                    $query->where('draft', '=', true)
+                        ->where('owned_by', '=', $this->currentUser()->id);
+                });
+        });
+    }
+
+    /**
+     * 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.
+     */
+    public function restrictEntityRelationQuery(Builder $query, string $tableName, string $entityIdColumn, string $entityTypeColumn): Builder
+    {
+        $tableDetails = ['tableName' => $tableName, 'entityIdColumn' => $entityIdColumn, 'entityTypeColumn' => $entityTypeColumn];
+        $pageMorphClass = (new Page())->getMorphClass();
+
+        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);
+                });
+            });
+    }
+
+    /**
+     * Add conditions to a query for a model that's a relation of a page, so only the model results
+     * on visible pages are returned by the query.
+     * Is effectively the same as "restrictEntityRelationQuery" but takes into account page drafts
+     * while not expecting a polymorphic relation, Just a simpler one-page-to-many-relations set-up.
+     */
+    public function restrictPageRelationQuery(Builder $query, string $tableName, string $pageIdColumn): Builder
+    {
+        $fullPageIdColumn = $tableName . '.' . $pageIdColumn;
+        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);
+                });
+            });
+    }
+
+    /**
+     * Get the current user.
+     */
+    protected function currentUser(): User
+    {
+        return user();
+    }
+
+    /**
+     * Get the roles for the current logged-in user.
+     *
+     * @return int[]
+     */
+    protected function getCurrentUserRoleIds(): array
+    {
+        if (auth()->guest()) {
+            return [Role::getSystemRole('public')->id];
+        }
+
+        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/PermissionService.php

@@ -1,719 +0,0 @@
-<?php
-
-namespace BookStack\Auth\Permissions;
-
-use BookStack\Auth\Role;
-use BookStack\Auth\User;
-use BookStack\Entities\Models\Book;
-use BookStack\Entities\Models\BookChild;
-use BookStack\Entities\Models\Bookshelf;
-use BookStack\Entities\Models\Chapter;
-use BookStack\Entities\Models\Entity;
-use BookStack\Entities\Models\Page;
-use BookStack\Model;
-use BookStack\Traits\HasCreatorAndUpdater;
-use BookStack\Traits\HasOwner;
-use Illuminate\Database\Connection;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Collection as EloquentCollection;
-use Illuminate\Database\Query\Builder as QueryBuilder;
-use Throwable;
-
-class PermissionService
-{
-    /**
-     * @var ?array
-     */
-    protected $userRoles = null;
-
-    /**
-     * @var ?User
-     */
-    protected $currentUserModel = null;
-
-    /**
-     * @var Connection
-     */
-    protected $db;
-
-    /**
-     * @var array
-     */
-    protected $entityCache;
-
-    /**
-     * PermissionService constructor.
-     */
-    public function __construct(Connection $db)
-    {
-        $this->db = $db;
-    }
-
-    /**
-     * Set the database connection.
-     */
-    public function setConnection(Connection $connection)
-    {
-        $this->db = $connection;
-    }
-
-    /**
-     * Prepare the local entity cache and ensure it's empty.
-     *
-     * @param Entity[] $entities
-     */
-    protected function readyEntityCache(array $entities = [])
-    {
-        $this->entityCache = [];
-
-        foreach ($entities as $entity) {
-            $class = get_class($entity);
-            if (!isset($this->entityCache[$class])) {
-                $this->entityCache[$class] = collect();
-            }
-            $this->entityCache[$class]->put($entity->id, $entity);
-        }
-    }
-
-    /**
-     * Get a book via ID, Checks local cache.
-     */
-    protected function getBook(int $bookId): ?Book
-    {
-        if (isset($this->entityCache[Book::class]) && $this->entityCache[Book::class]->has($bookId)) {
-            return $this->entityCache[Book::class]->get($bookId);
-        }
-
-        return Book::query()->withTrashed()->find($bookId);
-    }
-
-    /**
-     * Get a chapter via ID, Checks local cache.
-     */
-    protected function getChapter(int $chapterId): ?Chapter
-    {
-        if (isset($this->entityCache[Chapter::class]) && $this->entityCache[Chapter::class]->has($chapterId)) {
-            return $this->entityCache[Chapter::class]->get($chapterId);
-        }
-
-        return Chapter::query()
-            ->withTrashed()
-            ->find($chapterId);
-    }
-
-    /**
-     * Get the roles for the current logged in user.
-     */
-    protected function getCurrentUserRoles(): array
-    {
-        if (!is_null($this->userRoles)) {
-            return $this->userRoles;
-        }
-
-        if (auth()->guest()) {
-            $this->userRoles = [Role::getSystemRole('public')->id];
-        } else {
-            $this->userRoles = $this->currentUser()->roles->pluck('id')->values()->all();
-        }
-
-        return $this->userRoles;
-    }
-
-    /**
-     * Re-generate all entity permission from scratch.
-     */
-    public function buildJointPermissions()
-    {
-        JointPermission::query()->truncate();
-        $this->readyEntityCache();
-
-        // Get all roles (Should be the most limited dimension)
-        $roles = Role::query()->with('permissions')->get()->all();
-
-        // Chunk through all books
-        $this->bookFetchQuery()->chunk(5, function (EloquentCollection $books) use ($roles) {
-            $this->buildJointPermissionsForBooks($books, $roles);
-        });
-
-        // Chunk through all bookshelves
-        Bookshelf::query()->withTrashed()->select(['id', 'restricted', 'owned_by'])
-            ->chunk(50, function (EloquentCollection $shelves) use ($roles) {
-                $this->buildJointPermissionsForShelves($shelves, $roles);
-            });
-    }
-
-    /**
-     * Get a query for fetching a book with it's children.
-     */
-    protected function bookFetchQuery(): Builder
-    {
-        return Book::query()->withTrashed()
-            ->select(['id', 'restricted', 'owned_by'])->with([
-                'chapters' => function ($query) {
-                    $query->withTrashed()->select(['id', 'restricted', 'owned_by', 'book_id']);
-                },
-                'pages' => function ($query) {
-                    $query->withTrashed()->select(['id', 'restricted', 'owned_by', 'book_id', 'chapter_id']);
-                },
-            ]);
-    }
-
-    /**
-     * Build joint permissions for the given shelf and role combinations.
-     *
-     * @throws Throwable
-     */
-    protected function buildJointPermissionsForShelves(EloquentCollection $shelves, array $roles, bool $deleteOld = false)
-    {
-        if ($deleteOld) {
-            $this->deleteManyJointPermissionsForEntities($shelves->all());
-        }
-        $this->createManyJointPermissions($shelves->all(), $roles);
-    }
-
-    /**
-     * Build joint permissions for the given book and role combinations.
-     *
-     * @throws Throwable
-     */
-    protected function buildJointPermissionsForBooks(EloquentCollection $books, array $roles, bool $deleteOld = false)
-    {
-        $entities = clone $books;
-
-        /** @var Book $book */
-        foreach ($books->all() as $book) {
-            foreach ($book->getRelation('chapters') as $chapter) {
-                $entities->push($chapter);
-            }
-            foreach ($book->getRelation('pages') as $page) {
-                $entities->push($page);
-            }
-        }
-
-        if ($deleteOld) {
-            $this->deleteManyJointPermissionsForEntities($entities->all());
-        }
-        $this->createManyJointPermissions($entities->all(), $roles);
-    }
-
-    /**
-     * Rebuild the entity jointPermissions for a particular entity.
-     *
-     * @throws Throwable
-     */
-    public function buildJointPermissionsForEntity(Entity $entity)
-    {
-        $entities = [$entity];
-        if ($entity instanceof Book) {
-            $books = $this->bookFetchQuery()->where('id', '=', $entity->id)->get();
-            $this->buildJointPermissionsForBooks($books, Role::query()->get()->all(), true);
-
-            return;
-        }
-
-        /** @var BookChild $entity */
-        if ($entity->book) {
-            $entities[] = $entity->book;
-        }
-
-        if ($entity instanceof Page && $entity->chapter_id) {
-            $entities[] = $entity->chapter;
-        }
-
-        if ($entity instanceof Chapter) {
-            foreach ($entity->pages as $page) {
-                $entities[] = $page;
-            }
-        }
-
-        $this->buildJointPermissionsForEntities($entities);
-    }
-
-    /**
-     * Rebuild the entity jointPermissions for a collection of entities.
-     *
-     * @throws Throwable
-     */
-    public function buildJointPermissionsForEntities(array $entities)
-    {
-        $roles = Role::query()->get()->values()->all();
-        $this->deleteManyJointPermissionsForEntities($entities);
-        $this->createManyJointPermissions($entities, $roles);
-    }
-
-    /**
-     * Build the entity jointPermissions for a particular role.
-     */
-    public function buildJointPermissionForRole(Role $role)
-    {
-        $roles = [$role];
-        $this->deleteManyJointPermissionsForRoles($roles);
-
-        // Chunk through all books
-        $this->bookFetchQuery()->chunk(20, function ($books) use ($roles) {
-            $this->buildJointPermissionsForBooks($books, $roles);
-        });
-
-        // Chunk through all bookshelves
-        Bookshelf::query()->select(['id', 'restricted', 'owned_by'])
-            ->chunk(50, function ($shelves) use ($roles) {
-                $this->buildJointPermissionsForShelves($shelves, $roles);
-            });
-    }
-
-    /**
-     * Delete the entity jointPermissions attached to a particular role.
-     */
-    public function deleteJointPermissionsForRole(Role $role)
-    {
-        $this->deleteManyJointPermissionsForRoles([$role]);
-    }
-
-    /**
-     * Delete all of the entity jointPermissions for a list of entities.
-     *
-     * @param Role[] $roles
-     */
-    protected function deleteManyJointPermissionsForRoles($roles)
-    {
-        $roleIds = array_map(function ($role) {
-            return $role->id;
-        }, $roles);
-        JointPermission::query()->whereIn('role_id', $roleIds)->delete();
-    }
-
-    /**
-     * Delete the entity jointPermissions for a particular entity.
-     *
-     * @param Entity $entity
-     *
-     * @throws Throwable
-     */
-    public function deleteJointPermissionsForEntity(Entity $entity)
-    {
-        $this->deleteManyJointPermissionsForEntities([$entity]);
-    }
-
-    /**
-     * Delete all of the entity jointPermissions for a list of entities.
-     *
-     * @param Entity[] $entities
-     *
-     * @throws Throwable
-     */
-    protected function deleteManyJointPermissionsForEntities(array $entities)
-    {
-        if (count($entities) === 0) {
-            return;
-        }
-
-        $this->db->transaction(function () use ($entities) {
-            foreach (array_chunk($entities, 1000) as $entityChunk) {
-                $query = $this->db->table('joint_permissions');
-                foreach ($entityChunk as $entity) {
-                    $query->orWhere(function (QueryBuilder $query) use ($entity) {
-                        $query->where('entity_id', '=', $entity->id)
-                            ->where('entity_type', '=', $entity->getMorphClass());
-                    });
-                }
-                $query->delete();
-            }
-        });
-    }
-
-    /**
-     * Create & Save entity jointPermissions for many entities and roles.
-     *
-     * @param Entity[] $entities
-     * @param Role[]   $roles
-     *
-     * @throws Throwable
-     */
-    protected function createManyJointPermissions(array $entities, array $roles)
-    {
-        $this->readyEntityCache($entities);
-        $jointPermissions = [];
-
-        // Fetch Entity Permissions and create a mapping of entity restricted statuses
-        $entityRestrictedMap = [];
-        $permissionFetch = EntityPermission::query();
-        foreach ($entities as $entity) {
-            $entityRestrictedMap[$entity->getMorphClass() . ':' . $entity->id] = boolval($entity->getRawAttribute('restricted'));
-            $permissionFetch->orWhere(function ($query) use ($entity) {
-                $query->where('restrictable_id', '=', $entity->id)->where('restrictable_type', '=', $entity->getMorphClass());
-            });
-        }
-        $permissions = $permissionFetch->get();
-
-        // Create a mapping of explicit entity permissions
-        $permissionMap = [];
-        foreach ($permissions as $permission) {
-            $key = $permission->restrictable_type . ':' . $permission->restrictable_id . ':' . $permission->role_id . ':' . $permission->action;
-            $isRestricted = $entityRestrictedMap[$permission->restrictable_type . ':' . $permission->restrictable_id];
-            $permissionMap[$key] = $isRestricted;
-        }
-
-        // Create a mapping of role permissions
-        $rolePermissionMap = [];
-        foreach ($roles as $role) {
-            foreach ($role->permissions as $permission) {
-                $rolePermissionMap[$role->getRawAttribute('id') . ':' . $permission->getRawAttribute('name')] = true;
-            }
-        }
-
-        // Create Joint Permission Data
-        foreach ($entities as $entity) {
-            foreach ($roles as $role) {
-                foreach ($this->getActions($entity) as $action) {
-                    $jointPermissions[] = $this->createJointPermissionData($entity, $role, $action, $permissionMap, $rolePermissionMap);
-                }
-            }
-        }
-
-        $this->db->transaction(function () use ($jointPermissions) {
-            foreach (array_chunk($jointPermissions, 1000) as $jointPermissionChunk) {
-                $this->db->table('joint_permissions')->insert($jointPermissionChunk);
-            }
-        });
-    }
-
-    /**
-     * Get the actions related to an entity.
-     */
-    protected function getActions(Entity $entity): array
-    {
-        $baseActions = ['view', 'update', 'delete'];
-        if ($entity instanceof Chapter || $entity instanceof Book) {
-            $baseActions[] = 'page-create';
-        }
-        if ($entity instanceof Book) {
-            $baseActions[] = 'chapter-create';
-        }
-
-        return $baseActions;
-    }
-
-    /**
-     * Create entity permission data for an entity and role
-     * for a particular action.
-     */
-    protected function createJointPermissionData(Entity $entity, Role $role, string $action, array $permissionMap, array $rolePermissionMap): array
-    {
-        $permissionPrefix = (strpos($action, '-') === false ? ($entity->getType() . '-') : '') . $action;
-        $roleHasPermission = isset($rolePermissionMap[$role->getRawAttribute('id') . ':' . $permissionPrefix . '-all']);
-        $roleHasPermissionOwn = isset($rolePermissionMap[$role->getRawAttribute('id') . ':' . $permissionPrefix . '-own']);
-        $explodedAction = explode('-', $action);
-        $restrictionAction = end($explodedAction);
-
-        if ($role->system_name === 'admin') {
-            return $this->createJointPermissionDataArray($entity, $role, $action, true, true);
-        }
-
-        if ($entity->restricted) {
-            $hasAccess = $this->mapHasActiveRestriction($permissionMap, $entity, $role, $restrictionAction);
-
-            return $this->createJointPermissionDataArray($entity, $role, $action, $hasAccess, $hasAccess);
-        }
-
-        if ($entity instanceof Book || $entity instanceof Bookshelf) {
-            return $this->createJointPermissionDataArray($entity, $role, $action, $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, $role, $restrictionAction);
-        $hasPermissiveAccessToParents = !$book->restricted;
-
-        // For pages with a chapter, Check if explicit permissions are set on the Chapter
-        if ($entity instanceof Page && intval($entity->chapter_id) !== 0) {
-            $chapter = $this->getChapter($entity->chapter_id);
-            $hasPermissiveAccessToParents = $hasPermissiveAccessToParents && !$chapter->restricted;
-            if ($chapter->restricted) {
-                $hasExplicitAccessToParents = $this->mapHasActiveRestriction($permissionMap, $chapter, $role, $restrictionAction);
-            }
-        }
-
-        return $this->createJointPermissionDataArray(
-            $entity,
-            $role,
-            $action,
-            ($hasExplicitAccessToParents || ($roleHasPermission && $hasPermissiveAccessToParents)),
-            ($hasExplicitAccessToParents || ($roleHasPermissionOwn && $hasPermissiveAccessToParents))
-        );
-    }
-
-    /**
-     * Check for an active restriction in an entity map.
-     */
-    protected function mapHasActiveRestriction(array $entityMap, Entity $entity, Role $role, string $action): bool
-    {
-        $key = $entity->getMorphClass() . ':' . $entity->getRawAttribute('id') . ':' . $role->getRawAttribute('id') . ':' . $action;
-
-        return $entityMap[$key] ?? false;
-    }
-
-    /**
-     * Create an array of data with the information of an entity jointPermissions.
-     * Used to build data for bulk insertion.
-     */
-    protected function createJointPermissionDataArray(Entity $entity, Role $role, string $action, bool $permissionAll, bool $permissionOwn): array
-    {
-        return [
-            'role_id'            => $role->getRawAttribute('id'),
-            'entity_id'          => $entity->getRawAttribute('id'),
-            'entity_type'        => $entity->getMorphClass(),
-            'action'             => $action,
-            'has_permission'     => $permissionAll,
-            'has_permission_own' => $permissionOwn,
-            'owned_by'           => $entity->getRawAttribute('owned_by'),
-        ];
-    }
-
-    /**
-     * Checks if an entity has a restriction set upon it.
-     *
-     * @param HasCreatorAndUpdater|HasOwner $ownable
-     */
-    public function checkOwnableUserAccess(Model $ownable, string $permission): bool
-    {
-        $explodedPermission = explode('-', $permission);
-
-        $baseQuery = $ownable->newQuery()->where('id', '=', $ownable->id);
-        $action = end($explodedPermission);
-        $user = $this->currentUser();
-
-        $nonJointPermissions = ['restrictions', 'image', 'attachment', 'comment'];
-
-        // Handle non entity specific jointPermissions
-        if (in_array($explodedPermission[0], $nonJointPermissions)) {
-            $allPermission = $user && $user->can($permission . '-all');
-            $ownPermission = $user && $user->can($permission . '-own');
-            $ownerField = ($ownable instanceof Entity) ? 'owned_by' : 'created_by';
-            $isOwner = $user && $user->id === $ownable->$ownerField;
-
-            return $allPermission || ($isOwner && $ownPermission);
-        }
-
-        // Handle abnormal create jointPermissions
-        if ($action === 'create') {
-            $action = $permission;
-        }
-
-        $hasAccess = $this->entityRestrictionQuery($baseQuery, $action)->count() > 0;
-        $this->clean();
-
-        return $hasAccess;
-    }
-
-    /**
-     * Checks if a user has the given permission for any items in the system.
-     * Can be passed an entity instance to filter on a specific type.
-     */
-    public function checkUserHasPermissionOnAnything(string $permission, ?string $entityClass = null): bool
-    {
-        $userRoleIds = $this->currentUser()->roles()->select('id')->pluck('id')->toArray();
-        $userId = $this->currentUser()->id;
-
-        $permissionQuery = JointPermission::query()
-            ->where('action', '=', $permission)
-            ->whereIn('role_id', $userRoleIds)
-            ->where(function (Builder $query) use ($userId) {
-                $this->addJointHasPermissionCheck($query, $userId);
-            });
-
-        if (!is_null($entityClass)) {
-            $entityInstance = app($entityClass);
-            $permissionQuery = $permissionQuery->where('entity_type', '=', $entityInstance->getMorphClass());
-        }
-
-        $hasPermission = $permissionQuery->count() > 0;
-        $this->clean();
-
-        return $hasPermission;
-    }
-
-    /**
-     * The general query filter to remove all entities
-     * that the current user does not have access to.
-     */
-    protected function entityRestrictionQuery(Builder $query, string $action): Builder
-    {
-        $q = $query->where(function ($parentQuery) use ($action) {
-            $parentQuery->whereHas('jointPermissions', function ($permissionQuery) use ($action) {
-                $permissionQuery->whereIn('role_id', $this->getCurrentUserRoles())
-                    ->where('action', '=', $action)
-                    ->where(function (Builder $query) {
-                        $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
-                    });
-            });
-        });
-
-        $this->clean();
-
-        return $q;
-    }
-
-    /**
-     * Limited the given entity query so that the query will only
-     * return items that the user has permission for the given ability.
-     */
-    public function restrictEntityQuery(Builder $query, string $ability = 'view'): Builder
-    {
-        $this->clean();
-
-        return $query->where(function (Builder $parentQuery) use ($ability) {
-            $parentQuery->whereHas('jointPermissions', function (Builder $permissionQuery) use ($ability) {
-                $permissionQuery->whereIn('role_id', $this->getCurrentUserRoles())
-                    ->where('action', '=', $ability)
-                    ->where(function (Builder $query) {
-                        $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
-                    });
-            });
-        });
-    }
-
-    /**
-     * Extend the given page query to ensure draft items are not visible
-     * unless created by the given user.
-     */
-    public function enforceDraftVisibilityOnQuery(Builder $query): Builder
-    {
-        return $query->where(function (Builder $query) {
-            $query->where('draft', '=', false)
-                ->orWhere(function (Builder $query) {
-                    $query->where('draft', '=', true)
-                        ->where('owned_by', '=', $this->currentUser()->id);
-                });
-        });
-    }
-
-    /**
-     * Add restrictions for a generic entity.
-     */
-    public function enforceEntityRestrictions(Entity $entity, Builder $query, string $action = 'view'): Builder
-    {
-        if ($entity instanceof Page) {
-            // Prevent drafts being visible to others.
-            $this->enforceDraftVisibilityOnQuery($query);
-        }
-
-        return $this->entityRestrictionQuery($query, $action);
-    }
-
-    /**
-     * 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 filterRestrictedEntityRelations($query, string $tableName, string $entityIdColumn, string $entityTypeColumn, string $action = 'view')
-    {
-        $tableDetails = ['tableName' => $tableName, 'entityIdColumn' => $entityIdColumn, 'entityTypeColumn' => $entityTypeColumn];
-        $pageMorphClass = (new Page())->getMorphClass();
-
-        $q = $query->whereExists(function ($permissionQuery) use (&$tableDetails, $action) {
-            /** @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'])
-                ->where('joint_permissions.action', '=', $action)
-                ->whereIn('joint_permissions.role_id', $this->getCurrentUserRoles())
-                ->where(function (QueryBuilder $query) {
-                    $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
-                });
-        })->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);
-                });
-        });
-
-        $this->clean();
-
-        return $q;
-    }
-
-    /**
-     * Add conditions to a query to filter the selection to related entities
-     * where view permissions are granted.
-     */
-    public function filterRelatedEntity(string $entityClass, Builder $query, string $tableName, string $entityIdColumn): Builder
-    {
-        $fullEntityIdColumn = $tableName . '.' . $entityIdColumn;
-        $instance = new $entityClass();
-        $morphClass = $instance->getMorphClass();
-
-        $existsQuery = function ($permissionQuery) use ($fullEntityIdColumn, $morphClass) {
-            /** @var Builder $permissionQuery */
-            $permissionQuery->select('joint_permissions.role_id')->from('joint_permissions')
-                ->whereColumn('joint_permissions.entity_id', '=', $fullEntityIdColumn)
-                ->where('joint_permissions.entity_type', '=', $morphClass)
-                ->where('joint_permissions.action', '=', 'view')
-                ->whereIn('joint_permissions.role_id', $this->getCurrentUserRoles())
-                ->where(function (QueryBuilder $query) {
-                    $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
-                });
-        };
-
-        $q = $query->where(function ($query) use ($existsQuery, $fullEntityIdColumn) {
-            $query->whereExists($existsQuery)
-                ->orWhere($fullEntityIdColumn, '=', 0);
-        });
-
-        if ($instance instanceof Page) {
-            // Prevent visibility of non-owned draft pages
-            $q->whereExists(function (QueryBuilder $query) use ($fullEntityIdColumn) {
-                $query->select('id')->from('pages')
-                    ->whereColumn('pages.id', '=', $fullEntityIdColumn)
-                    ->where(function (QueryBuilder $query) {
-                        $query->where('pages.draft', '=', false)
-                            ->orWhere('pages.owned_by', '=', $this->currentUser()->id);
-                    });
-            });
-        }
-
-        $this->clean();
-
-        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);
-        });
-    }
-
-    /**
-     * Get the current user.
-     */
-    private function currentUser(): User
-    {
-        if (is_null($this->currentUserModel)) {
-            $this->currentUserModel = user();
-        }
-
-        return $this->currentUserModel;
-    }
-
-    /**
-     * Clean the cached user elements.
-     */
-    private function clean(): void
-    {
-        $this->currentUserModel = null;
-        $this->userRoles = null;
-    }
-}

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

@@ -11,20 +11,12 @@ use Illuminate\Database\Eloquent\Collection;
 
 class PermissionsRepo
 {
-    protected $permission;
-    protected $role;
-    protected $permissionService;
+    protected JointPermissionBuilder $permissionBuilder;
+    protected array $systemRoles = ['admin', 'public'];
 
-    protected $systemRoles = ['admin', 'public'];
-
-    /**
-     * PermissionsRepo constructor.
-     */
-    public function __construct(RolePermission $permission, Role $role, PermissionService $permissionService)
+    public function __construct(JointPermissionBuilder $permissionBuilder)
     {
-        $this->permission = $permission;
-        $this->role = $role;
-        $this->permissionService = $permissionService;
+        $this->permissionBuilder = $permissionBuilder;
     }
 
     /**
@@ -32,7 +24,7 @@ class PermissionsRepo
      */
     public function getAllRoles(): Collection
     {
-        return $this->role->all();
+        return Role::query()->get();
     }
 
     /**
@@ -40,15 +32,15 @@ class PermissionsRepo
      */
     public function getAllRolesExcept(Role $role): Collection
     {
-        return $this->role->where('id', '!=', $role->id)->get();
+        return Role::query()->where('id', '!=', $role->id)->get();
     }
 
     /**
      * Get a role via its ID.
      */
-    public function getRoleById($id): Role
+    public function getRoleById(int $id): Role
     {
-        return $this->role->newQuery()->findOrFail($id);
+        return Role::query()->findOrFail($id);
     }
 
     /**
@@ -56,13 +48,14 @@ class PermissionsRepo
      */
     public function saveNewRole(array $roleData): Role
     {
-        $role = $this->role->newInstance($roleData);
-        $role->mfa_enforced = ($roleData['mfa_enforced'] ?? 'false') === 'true';
+        $role = new Role($roleData);
+        $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->permissionService->buildJointPermissionForRole($role);
+        $this->permissionBuilder->rebuildForRole($role);
+
         Activity::add(ActivityType::ROLE_CREATE, $role);
 
         return $role;
@@ -70,43 +63,46 @@ 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
     {
-        /** @var Role $role */
-        $role = $this->role->newQuery()->findOrFail($roleId);
+        $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->permissionService->buildJointPermissionForRole($role);
-        Activity::add(ActivityType::ROLE_UPDATE, $role);
-    }
-
-    /**
-     * Assign an list of permission names to an role.
-     */
-    protected function assignRolePermissions(Role $role, array $permissionNameArray = [])
-    {
-        $permissions = [];
-        $permissionNameArray = array_values($permissionNameArray);
-
-        if ($permissionNameArray) {
-            $permissions = $this->permission->newQuery()
+        if (!empty($permissionNameArray)) {
+            $permissions = RolePermission::query()
                 ->whereIn('name', $permissionNameArray)
                 ->pluck('id')
                 ->toArray();
@@ -118,16 +114,15 @@ 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
     {
-        /** @var Role $role */
-        $role = $this->role->newQuery()->findOrFail($roleId);
+        $role = $this->getRoleById($roleId);
 
         // Prevent deleting admin role or default registration role.
         if ($role->system_name && in_array($role->system_name, $this->systemRoles)) {
@@ -136,15 +131,16 @@ class PermissionsRepo
             throw new PermissionsException(trans('errors.role_registration_default_cannot_delete'));
         }
 
-        if ($migrateRoleId) {
-            $newRole = $this->role->newQuery()->find($migrateRoleId);
+        if ($migrateRoleId !== 0) {
+            $newRole = Role::query()->find($migrateRoleId);
             if ($newRole) {
                 $users = $role->users()->pluck('id')->toArray();
                 $newRole->users()->sync($users);
             }
         }
 
-        $this->permissionService->deleteJointPermissionsForRole($role);
+        $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

@@ -0,0 +1,28 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+use BookStack\Entities\Models\Entity;
+
+class SimpleEntityData
+{
+    public int $id;
+    public string $type;
+    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/UserContentCounts.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace BookStack\Auth\Queries;
+
+use BookStack\Auth\User;
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Bookshelf;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Page;
+
+/**
+ * Get asset created counts for the given user.
+ */
+class UserContentCounts
+{
+    /**
+     * @return array{pages: int, chapters: int, books: int, shelves: int}
+     */
+    public function run(User $user): array
+    {
+        $createdBy = ['created_by' => $user->id];
+
+        return [
+            'pages'    => Page::visible()->where($createdBy)->count(),
+            'chapters' => Chapter::visible()->where($createdBy)->count(),
+            'books'    => Book::visible()->where($createdBy)->count(),
+            'shelves'  => Bookshelf::visible()->where($createdBy)->count(),
+        ];
+    }
+}

app/Auth/Queries/UserRecentlyCreatedContent.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace BookStack\Auth\Queries;
+
+use BookStack\Auth\User;
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Bookshelf;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Page;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Collection;
+
+/**
+ * Get the recently created content for the provided user.
+ */
+class UserRecentlyCreatedContent
+{
+    /**
+     * @return array{pages: Collection, chapters: Collection, books: Collection, shelves: Collection}
+     */
+    public function run(User $user, int $count): array
+    {
+        $query = function (Builder $query) use ($user, $count) {
+            return $query->orderBy('created_at', 'desc')
+                ->where('created_by', '=', $user->id)
+                ->take($count)
+                ->get();
+        };
+
+        return [
+            'pages'    => $query(Page::visible()->where('draft', '=', false)),
+            'chapters' => $query(Chapter::visible()),
+            'books'    => $query(Book::visible()),
+            'shelves'  => $query(Bookshelf::visible()),
+        ];
+    }
+}

app/Auth/Queries/UsersAllPaginatedAndSorted.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace BookStack\Auth\Queries;
+
+use BookStack\Auth\User;
+use BookStack\Util\SimpleListOptions;
+use Illuminate\Pagination\LengthAwarePaginator;
+
+/**
+ * Get all the users with their permissions in a paginated format.
+ * Note: Due to the use of email search this should only be used when
+ * user is assumed to be trusted. (Admin users).
+ * Email search can be abused to extract email addresses.
+ */
+class UsersAllPaginatedAndSorted
+{
+    public function run(int $count, SimpleListOptions $listOptions): LengthAwarePaginator
+    {
+        $sort = $listOptions->getSort();
+        if ($sort === 'created_at') {
+            $sort = 'users.created_at';
+        }
+
+        $query = User::query()->select(['*'])
+            ->scopes(['withLastActivityAt'])
+            ->with(['roles', 'avatar'])
+            ->withCount('mfaValues')
+            ->orderBy($sort, $listOptions->getOrder());
+
+        if ($listOptions->getSearch()) {
+            $term = '%' . $listOptions->getSearch() . '%';
+            $query->where(function ($query) use ($term) {
+                $query->where('name', 'like', $term)
+                    ->orWhere('email', 'like', $term);
+            });
+        }
+
+        return $query->paginate($count);
+    }
+}

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,7 +27,13 @@ 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.
@@ -52,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.
      */
@@ -96,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,22 +72,25 @@ 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',
+        'created_at', 'updated_at', 'image_id', 'roles', 'avatar', 'user_id', 'pivot',
     ];
 
     /**
      * This holds the user's permissions when loaded.
-     *
-     * @var ?Collection
      */
-    protected $permissions;
+    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.
      *
      * @var null|User
      */
-    protected static $defaultUser = null;
+    protected static ?User $defaultUser = null;
 
     /**
      * Returns the default public user.
@@ -146,7 +149,7 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
      */
     public function attachDefaultRole(): void
     {
-        $roleId = setting('registration-role');
+        $roleId = intval(setting('registration-role'));
         if ($roleId && $this->roles()->where('id', '=', $roleId)->count() === 0) {
             $this->roles()->attach($roleId);
         }
@@ -165,7 +168,7 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
     }
 
     /**
-     * Get all permissions belonging to a the current user.
+     * Get all permissions belonging to the current user.
      */
     protected function permissions(): Collection
     {
@@ -197,6 +200,7 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
     public function attachRole(Role $role)
     {
         $this->roles()->attach($role->id);
+        $this->unsetRelation('roles');
     }
 
     /**
@@ -235,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

@@ -2,30 +2,30 @@
 
 namespace BookStack\Auth;
 
+use BookStack\Actions\ActivityType;
+use BookStack\Auth\Access\UserInviteService;
 use BookStack\Entities\EntityProvider;
-use BookStack\Entities\Models\Book;
-use BookStack\Entities\Models\Bookshelf;
-use BookStack\Entities\Models\Chapter;
-use BookStack\Entities\Models\Page;
-use BookStack\Exceptions\NotFoundException;
+use BookStack\Exceptions\NotifyException;
 use BookStack\Exceptions\UserUpdateException;
+use BookStack\Facades\Activity;
 use BookStack\Uploads\UserAvatars;
 use Exception;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Collection;
-use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
 
 class UserRepo
 {
-    protected $userAvatar;
+    protected UserAvatars $userAvatar;
+    protected UserInviteService $inviteService;
 
     /**
      * UserRepo constructor.
      */
-    public function __construct(UserAvatars $userAvatar)
+    public function __construct(UserAvatars $userAvatar, UserInviteService $inviteService)
     {
         $this->userAvatar = $userAvatar;
+        $this->inviteService = $inviteService;
     }
 
     /**
@@ -53,70 +53,167 @@ class UserRepo
     }
 
     /**
-     * Get all the users with their permissions.
+     * Create a new basic instance of user with the given pre-validated data.
+     *
+     * @param array{name: string, email: string, password: ?string, external_auth_id: ?string, language: ?string, roles: ?array} $data
      */
-    public function getAllUsers(): Collection
+    public function createWithoutActivity(array $data, bool $emailConfirmed = false): User
     {
-        return User::query()->with('roles', 'avatar')->orderBy('name', 'asc')->get();
-    }
+        $user = new User();
+        $user->name = $data['name'];
+        $user->email = $data['email'];
+        $user->password = Hash::make(empty($data['password']) ? Str::random(32) : $data['password']);
+        $user->email_confirmed = $emailConfirmed;
+        $user->external_auth_id = $data['external_auth_id'] ?? '';
 
-    /**
-     * Get all the users with their permissions in a paginated format.
-     * Note: Due to the use of email search this should only be used when
-     * user is assumed to be trusted. (Admin users).
-     * Email search can be abused to extract email addresses.
-     */
-    public function getAllUsersPaginatedAndSorted(int $count, array $sortData): LengthAwarePaginator
-    {
-        $sort = $sortData['sort'];
+        $user->refreshSlug();
+        $user->save();
 
-        $query = User::query()->select(['*'])
-            ->scopes(['withLastActivityAt'])
-            ->with(['roles', 'avatar'])
-            ->withCount('mfaValues')
-            ->orderBy($sort, $sortData['order']);
-
-        if ($sortData['search']) {
-            $term = '%' . $sortData['search'] . '%';
-            $query->where(function ($query) use ($term) {
-                $query->where('name', 'like', $term)
-                    ->orWhere('email', 'like', $term);
-            });
+        if (!empty($data['language'])) {
+            setting()->putUser($user, 'language', $data['language']);
         }
 
-        return $query->paginate($count);
-    }
+        if (isset($data['roles'])) {
+            $this->setUserRoles($user, $data['roles']);
+        }
 
-    /**
-     * Creates a new user and attaches a role to them.
-     */
-    public function registerNew(array $data, bool $emailConfirmed = false): User
-    {
-        $user = $this->create($data, $emailConfirmed);
-        $user->attachDefaultRole();
         $this->downloadAndAssignUserAvatar($user);
 
         return $user;
     }
 
     /**
-     * Assign a user to a system-level role.
+     * As per "createWithoutActivity" but records a "create" activity.
      *
-     * @throws NotFoundException
+     * @param array{name: string, email: string, password: ?string, external_auth_id: ?string, language: ?string, roles: ?array} $data
      */
-    public function attachSystemRole(User $user, string $systemRoleName)
+    public function create(array $data, bool $sendInvite = false): User
     {
-        $role = Role::getSystemRole($systemRoleName);
-        if (is_null($role)) {
-            throw new NotFoundException("Role '{$systemRoleName}' not found");
+        $user = $this->createWithoutActivity($data, true);
+
+        if ($sendInvite) {
+            $this->inviteService->sendInvitation($user);
+        }
+
+        Activity::add(ActivityType::USER_CREATE, $user);
+
+        return $user;
+    }
+
+    /**
+     * Update the given user with the given data.
+     *
+     * @param array{name: ?string, email: ?string, external_auth_id: ?string, password: ?string, roles: ?array<int>, language: ?string} $data
+     *
+     * @throws UserUpdateException
+     */
+    public function update(User $user, array $data, bool $manageUsersAllowed): User
+    {
+        if (!empty($data['name'])) {
+            $user->name = $data['name'];
+            $user->refreshSlug();
+        }
+
+        if (!empty($data['email']) && $manageUsersAllowed) {
+            $user->email = $data['email'];
+        }
+
+        if (!empty($data['external_auth_id']) && $manageUsersAllowed) {
+            $user->external_auth_id = $data['external_auth_id'];
+        }
+
+        if (isset($data['roles']) && $manageUsersAllowed) {
+            $this->setUserRoles($user, $data['roles']);
+        }
+
+        if (!empty($data['password'])) {
+            $user->password = Hash::make($data['password']);
+        }
+
+        if (!empty($data['language'])) {
+            setting()->putUser($user, 'language', $data['language']);
+        }
+
+        $user->save();
+        Activity::add(ActivityType::USER_UPDATE, $user);
+
+        return $user;
+    }
+
+    /**
+     * Remove the given user from storage, Delete all related content.
+     *
+     * @throws Exception
+     */
+    public function destroy(User $user, ?int $newOwnerId = null)
+    {
+        $this->ensureDeletable($user);
+
+        $user->socialAccounts()->delete();
+        $user->apiTokens()->delete();
+        $user->favourites()->delete();
+        $user->mfaValues()->delete();
+        $user->delete();
+
+        // 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)) {
+                $this->migrateOwnership($user, $newOwner);
+            }
+        }
+
+        Activity::add(ActivityType::USER_DELETE, $user);
+    }
+
+    /**
+     * @throws NotifyException
+     */
+    protected function ensureDeletable(User $user): void
+    {
+        if ($this->isOnlyAdmin($user)) {
+            throw new NotifyException(trans('errors.users_cannot_delete_only_admin'), $user->getEditUrl());
+        }
+
+        if ($user->system_name === 'public') {
+            throw new NotifyException(trans('errors.users_cannot_delete_guest'), $user->getEditUrl());
+        }
+    }
+
+    /**
+     * Migrate ownership of items in the system from one user to another.
+     */
+    protected function migrateOwnership(User $fromUser, User $toUser)
+    {
+        $entities = (new EntityProvider())->all();
+        foreach ($entities as $instance) {
+            $instance->newQuery()->where('owned_by', '=', $fromUser->id)
+                ->update(['owned_by' => $toUser->id]);
+        }
+    }
+
+    /**
+     * Get an avatar image for a user and set it as their avatar.
+     * Returns early if avatars disabled or not set in config.
+     */
+    protected function downloadAndAssignUserAvatar(User $user): void
+    {
+        try {
+            $this->userAvatar->fetchAndAssignToUser($user);
+        } catch (Exception $e) {
+            Log::error('Failed to save user avatar image');
         }
-        $user->attachRole($role);
     }
 
     /**
      * Checks if the give user is the only admin.
      */
-    public function isOnlyAdmin(User $user): bool
+    protected function isOnlyAdmin(User $user): bool
     {
         if (!$user->hasSystemRole('admin')) {
             return false;
@@ -135,8 +232,10 @@ class UserRepo
      *
      * @throws UserUpdateException
      */
-    public function setUserRoles(User $user, array $roles)
+    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());
         }
@@ -159,117 +258,4 @@ class UserRepo
 
         return false;
     }
-
-    /**
-     * Create a new basic instance of user.
-     */
-    public function create(array $data, bool $emailConfirmed = false): User
-    {
-        $details = [
-            'name'             => $data['name'],
-            'email'            => $data['email'],
-            'password'         => bcrypt($data['password']),
-            'email_confirmed'  => $emailConfirmed,
-            'external_auth_id' => $data['external_auth_id'] ?? '',
-        ];
-
-        $user = new User();
-        $user->forceFill($details);
-        $user->refreshSlug();
-        $user->save();
-
-        return $user;
-    }
-
-    /**
-     * Remove the given user from storage, Delete all related content.
-     *
-     * @throws Exception
-     */
-    public function destroy(User $user, ?int $newOwnerId = null)
-    {
-        $user->socialAccounts()->delete();
-        $user->apiTokens()->delete();
-        $user->favourites()->delete();
-        $user->mfaValues()->delete();
-        $user->delete();
-
-        // Delete user profile images
-        $this->userAvatar->destroyAllForUser($user);
-
-        if (!empty($newOwnerId)) {
-            $newOwner = User::query()->find($newOwnerId);
-            if (!is_null($newOwner)) {
-                $this->migrateOwnership($user, $newOwner);
-            }
-        }
-    }
-
-    /**
-     * Migrate ownership of items in the system from one user to another.
-     */
-    protected function migrateOwnership(User $fromUser, User $toUser)
-    {
-        $entities = (new EntityProvider())->all();
-        foreach ($entities as $instance) {
-            $instance->newQuery()->where('owned_by', '=', $fromUser->id)
-                ->update(['owned_by' => $toUser->id]);
-        }
-    }
-
-    /**
-     * Get the recently created content for this given user.
-     */
-    public function getRecentlyCreated(User $user, int $count = 20): array
-    {
-        $query = function (Builder $query) use ($user, $count) {
-            return $query->orderBy('created_at', 'desc')
-                ->where('created_by', '=', $user->id)
-                ->take($count)
-                ->get();
-        };
-
-        return [
-            'pages'    => $query(Page::visible()->where('draft', '=', false)),
-            'chapters' => $query(Chapter::visible()),
-            'books'    => $query(Book::visible()),
-            'shelves'  => $query(Bookshelf::visible()),
-        ];
-    }
-
-    /**
-     * Get asset created counts for the give user.
-     */
-    public function getAssetCounts(User $user): array
-    {
-        $createdBy = ['created_by' => $user->id];
-
-        return [
-            'pages'       => Page::visible()->where($createdBy)->count(),
-            'chapters'    => Chapter::visible()->where($createdBy)->count(),
-            'books'       => Book::visible()->where($createdBy)->count(),
-            'shelves'     => Bookshelf::visible()->where($createdBy)->count(),
-        ];
-    }
-
-    /**
-     * Get the roles in the system that are assignable to a user.
-     */
-    public function getAllRoles(): Collection
-    {
-        return Role::query()->orderBy('display_name', 'asc')->get();
-    }
-
-    /**
-     * Get an avatar image for a user and set it as their avatar.
-     * Returns early if avatars disabled or not set in config.
-     */
-    public function downloadAndAssignUserAvatar(User $user): void
-    {
-        try {
-            $this->userAvatar->fetchAndAssignToUser($user);
-        } catch (Exception $e) {
-            Log::error('Failed to save user avatar image');
-        }
-    }
 }

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
@@ -57,6 +59,17 @@ return [
     // Space separated if multiple. BookStack host domain is auto-inferred.
     'iframe_hosts' => env('ALLOWED_IFRAME_HOSTS', null),
 
+    // A list of sources/hostnames that can be loaded within iframes within BookStack.
+    // Space separated if multiple. BookStack host domain is auto-inferred.
+    // Can be set to a lone "*" to allow all sources for iframe content (Not advised).
+    // Defaults to a set of common services.
+    // Current host and source for the "DRAWIO" setting will be auto-appended to the sources configured.
+    'iframe_sources' => env('ALLOWED_IFRAME_SOURCES', 'https://*.draw.io https://*.youtube.com https://*.youtube-nocookie.com https://*.vimeo.com'),
+
+    // Alter the precision of IP addresses stored by BookStack.
+    // Integer value between 0 (IP hidden) to 4 (Full IP usage)
+    'ip_address_precision' => env('IP_ADDRESS_PRECISION', 4),
+
     // Application timezone for back-end date functions.
     'timezone' => env('APP_TIMEZONE', 'UTC'),
 
@@ -64,7 +77,7 @@ return [
     'locale' => env('APP_LANG', 'en'),
 
     // Locales available
-    'locales' => ['en', 'ar', 'bg', 'bs', 'ca', 'cs', 'da', 'de', 'de_informal', 'es', 'es_AR', 'et', 'fa', 'fr', 'he', 'hr', 'hu', 'id', 'it', 'ja', 'ko', 'lt', 'lv', 'nl', 'nb', 'pt', 'pt_BR', 'sk', 'sl', 'sv', 'pl',  'ru', 'th', 'tr', 'uk', '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',
@@ -87,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...
@@ -103,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,
@@ -110,94 +131,37 @@ 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,
 
         // Third Party
         'ImageTool' => Intervention\Image\Facades\Image::class,
-        'DomPDF'    => Barryvdh\DomPDF\Facade::class,
-        'SnappyPDF' => Barryvdh\Snappy\Facades\SnappyPdf::class,
 
         // Custom BookStack
         'Activity'    => BookStack\Facades\Activity::class,
-        'Permissions' => BookStack\Facades\Permissions::class,
         'Theme'       => BookStack\Facades\Theme::class,
-    ],
+    ])->toArray(),
 
     // Proxy configuration
     'proxies' => env('APP_PROXIES', ''),

app/Config/auth.php

@@ -13,6 +13,10 @@ return [
     // Options: standard, ldap, saml2, oidc
     'method' => env('AUTH_METHOD', 'standard'),
 
+    // Automatically initiate login via external auth system if it's the sole auth method.
+    // Works with saml2 or oidc auth methods.
+    'auto_initiate' => env('AUTH_AUTO_INITIATE', false),
+
     // Authentication Defaults
     // This option controls the default authentication "guard" and password
     // reset options for your application.

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

@@ -8,11 +8,16 @@
  * Do not edit this file unless you're happy to maintain any changes yourself.
  */
 
+$dompdfPaperSizeMap = [
+    'a4'     => 'a4',
+    'letter' => 'letter',
+];
+
 return [
 
     'show_warnings' => false,   // Throw an Exception on warnings from dompdf
-    'orientation'   => 'portrait',
-    'defines'       => [
+
+    'options'       => [
         /**
          * The location of the DOMPDF font directory.
          *
@@ -73,15 +78,25 @@ return [
         'chroot' => realpath(public_path()),
 
         /**
-         * Whether to use Unicode fonts or not.
+         * Protocol whitelist.
          *
-         * When set to true the PDF backend must be set to "CPDF" and fonts must be
-         * loaded via load_font.php.
+         * Protocols and PHP wrappers allowed in URIs, and the validation rules
+         * that determine if a resouce may be loaded. Full support is not guaranteed
+         * for the protocols/wrappers specified
+         * by this array.
          *
-         * When enabled, dompdf can support all Unicode glyphs. Any glyphs used in a
-         * document must be present in your fonts, however.
+         * @var array
          */
-        'unicode_enabled' => true,
+        'allowed_protocols' => [
+            'file://'  => ['rules' => []],
+            'http://'  => ['rules' => []],
+            'https://' => ['rules' => []],
+        ],
+
+        /**
+         * @var string
+         */
+        'log_output_file' => null,
 
         /**
          * Whether to enable font subsetting or not.
@@ -150,7 +165,16 @@ return [
          *
          * @see CPDF_Adapter::PAPER_SIZES for valid sizes ('letter', 'legal', 'A4', etc.)
          */
-        'default_paper_size' => 'a4',
+        'default_paper_size' => $dompdfPaperSizeMap[env('EXPORT_PAGE_SIZE', 'a4')] ?? 'a4',
+
+        /**
+         * The default paper orientation.
+         *
+         * The orientation of the page (portrait or landscape).
+         *
+         * @var string
+         */
+        'default_paper_orientation' => 'portrait',
 
         /**
          * The default font family.
@@ -254,10 +278,13 @@ return [
         'enable_css_float' => true,
 
         /**
-         * Use the more-than-experimental HTML5 Lib parser.
+         * Use the HTML5 Lib parser.
+         *
+         * @deprecated This feature is now always on in dompdf 2.x
+         *
+         * @var bool
          */
-        'enable_html5parser' => true,
-
+        'enable_html5_parser' => true,
     ],
 
 ];

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/services.php

@@ -119,6 +119,7 @@ return [
     'ldap' => [
         'server'                 => env('LDAP_SERVER', false),
         'dump_user_details'      => env('LDAP_DUMP_USER_DETAILS', false),
+        'dump_user_groups'       => env('LDAP_DUMP_USER_GROUPS', false),
         'dn'                     => env('LDAP_DN', false),
         'pass'                   => env('LDAP_PASS', false),
         'base_dn'                => env('LDAP_BASE_DN', false),

app/Config/session.php

@@ -72,7 +72,7 @@ return [
     // to the server if the browser has a HTTPS connection. This will keep
     // the cookie from being sent to you if it can not be done securely.
     'secure' => env('SESSION_SECURE_COOKIE', null)
-        ?? Str::startsWith(env('APP_URL'), 'https:'),
+        ?? Str::startsWith(env('APP_URL', ''), 'https:'),
 
     // HTTP Access Only
     // Setting this value to true will prevent JavaScript from accessing the

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

@@ -8,13 +8,19 @@
  * Do not edit this file unless you're happy to maintain any changes yourself.
  */
 
+$snappyPaperSizeMap = [
+    'a4'     => 'A4',
+    'letter' => 'Letter',
+];
+
 return [
     'pdf' => [
         'enabled' => true,
         'binary'  => file_exists(base_path('wkhtmltopdf')) ? base_path('wkhtmltopdf') : env('WKHTMLTOPDF', false),
         'timeout' => false,
         'options' => [
-            'outline' => true,
+            'outline'   => true,
+            'page-size' => $snappyPaperSizeMap[env('EXPORT_PAGE_SIZE', 'a4')] ?? 'A4',
         ],
         'env'     => [],
     ],

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/CreateAdmin.php

@@ -2,9 +2,12 @@
 
 namespace BookStack\Console\Commands;
 
+use BookStack\Auth\Role;
 use BookStack\Auth\UserRepo;
+use BookStack\Exceptions\NotFoundException;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Validator;
+use Illuminate\Support\Str;
 use Illuminate\Validation\Rules\Password;
 use Illuminate\Validation\Rules\Unique;
 use Symfony\Component\Console\Command\Command as SymfonyCommand;
@@ -19,7 +22,8 @@ class CreateAdmin extends Command
     protected $signature = 'bookstack:create-admin
                             {--email= : The email address for the new admin user}
                             {--name= : The name of the new admin user}
-                            {--password= : The password to assign to the new admin user}';
+                            {--password= : The password to assign to the new admin user}
+                            {--external-auth-id= : The external authentication system id for the new admin user (SAML2/LDAP/OIDC)}';
 
     /**
      * The console command description.
@@ -42,28 +46,35 @@ class CreateAdmin extends Command
     /**
      * Execute the console command.
      *
-     * @throws \BookStack\Exceptions\NotFoundException
+     * @throws NotFoundException
      *
      * @return mixed
      */
     public function handle()
     {
-        $details = $this->options();
+        $details = $this->snakeCaseOptions();
 
         if (empty($details['email'])) {
             $details['email'] = $this->ask('Please specify an email address for the new admin user');
         }
+
         if (empty($details['name'])) {
             $details['name'] = $this->ask('Please specify a name for the new admin user');
         }
+
         if (empty($details['password'])) {
-            $details['password'] = $this->ask('Please specify a password for the new admin user (8 characters min)');
+            if (empty($details['external_auth_id'])) {
+                $details['password'] = $this->ask('Please specify a password for the new admin user (8 characters min)');
+            } else {
+                $details['password'] = Str::random(32);
+            }
         }
 
         $validator = Validator::make($details, [
-            'email'    => ['required', 'email', 'min:5', new Unique('users', 'email')],
-            'name'     => ['required', 'min:2'],
-            'password' => ['required', Password::default()],
+            'email'            => ['required', 'email', 'min:5', new Unique('users', 'email')],
+            'name'             => ['required', 'min:2'],
+            'password'         => ['required_without:external_auth_id', Password::default()],
+            'external_auth_id' => ['required_without:password'],
         ]);
 
         if ($validator->fails()) {
@@ -74,9 +85,8 @@ class CreateAdmin extends Command
             return SymfonyCommand::FAILURE;
         }
 
-        $user = $this->userRepo->create($validator->validated());
-        $this->userRepo->attachSystemRole($user, 'admin');
-        $this->userRepo->downloadAndAssignUserAvatar($user);
+        $user = $this->userRepo->createWithoutActivity($validator->validated());
+        $user->attachRole(Role::getSystemRole('admin'));
         $user->email_confirmed = true;
         $user->save();
 
@@ -84,4 +94,14 @@ class CreateAdmin extends Command
 
         return SymfonyCommand::SUCCESS;
     }
+
+    protected function snakeCaseOptions(): array
+    {
+        $returnOpts = [];
+        foreach ($this->options() as $key => $value) {
+            $returnOpts[str_replace('-', '_', $key)] = $value;
+        }
+
+        return $returnOpts;
+    }
 }

app/Console/Commands/DeleteUsers.php

@@ -15,8 +15,6 @@ class DeleteUsers extends Command
      */
     protected $signature = 'bookstack:delete-users';
 
-    protected $user;
-
     protected $userRepo;
 
     /**
@@ -26,9 +24,8 @@ class DeleteUsers extends Command
      */
     protected $description = 'Delete users that are not "admin" or system users';
 
-    public function __construct(User $user, UserRepo $userRepo)
+    public function __construct(UserRepo $userRepo)
     {
-        $this->user = $user;
         $this->userRepo = $userRepo;
         parent::__construct();
     }
@@ -38,8 +35,8 @@ class DeleteUsers extends Command
         $confirm = $this->ask('This will delete all users from the system that are not "admin" or system users. Are you sure you want to continue? (Type "yes" to continue)');
         $numDeleted = 0;
         if (strtolower(trim($confirm)) === 'yes') {
-            $totalUsers = $this->user->count();
-            $users = $this->user->where('system_name', '=', null)->with('roles')->get();
+            $totalUsers = User::query()->count();
+            $users = User::query()->whereNull('system_name')->with('roles')->get();
             foreach ($users as $user) {
                 if ($user->hasSystemRole('admin')) {
                     // don't delete users with "admin" role

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

@@ -2,8 +2,9 @@
 
 namespace BookStack\Console\Commands;
 
-use BookStack\Auth\Permissions\PermissionService;
+use BookStack\Auth\Permissions\JointPermissionBuilder;
 use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
 
 class RegeneratePermissions extends Command
 {
@@ -21,19 +22,14 @@ class RegeneratePermissions extends Command
      */
     protected $description = 'Regenerate all system permissions';
 
-    /**
-     * The service to handle the permission system.
-     *
-     * @var PermissionService
-     */
-    protected $permissionService;
+    protected JointPermissionBuilder $permissionBuilder;
 
     /**
      * Create a new command instance.
      */
-    public function __construct(PermissionService $permissionService)
+    public function __construct(JointPermissionBuilder $permissionBuilder)
     {
-        $this->permissionService = $permissionService;
+        $this->permissionBuilder = $permissionBuilder;
         parent::__construct();
     }
 
@@ -44,15 +40,17 @@ class RegeneratePermissions extends Command
      */
     public function handle()
     {
-        $connection = \DB::getDefaultConnection();
-        if ($this->option('database') !== null) {
-            \DB::setDefaultConnection($this->option('database'));
-            $this->permissionService->setConnection(\DB::connection($this->option('database')));
+        $connection = DB::getDefaultConnection();
+
+        if ($this->option('database')) {
+            DB::setDefaultConnection($this->option('database'));
         }
 
-        $this->permissionService->buildJointPermissions();
+        $this->permissionBuilder->rebuildForAll();
 
-        \DB::setDefaultConnection($connection);
+        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,15 +86,11 @@ class Bookshelf extends Entity implements HasCoverImage
      */
     public function coverImageTypeKey(): string
     {
-        return 'cover_shelf';
+        return 'cover_bookshelf';
     }
 
     /**
      * Check if this shelf contains the given book.
-     *
-     * @param Book $book
-     *
-     * @return bool
      */
     public function contains(Book $book): bool
     {
@@ -103,8 +99,6 @@ class Bookshelf extends Entity implements HasCoverImage
 
     /**
      * Add a book to the end of this shelf.
-     *
-     * @param Book $book
      */
     public function appendBook(Book $book)
     {
@@ -115,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/Deletion.php

@@ -10,10 +10,16 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 /**
+ * @property int       $id
+ * @property int       $deleted_by
+ * @property string    $deletable_type
+ * @property int       $deletable_id
  * @property Deletable $deletable
  */
 class Deletion extends Model implements Loggable
 {
+    protected $hidden = [];
+
     /**
      * Get the related deletable record.
      */

app/Entities/Models/Entity.php

@@ -9,15 +9,18 @@ use BookStack\Actions\Tag;
 use BookStack\Actions\View;
 use BookStack\Auth\Permissions\EntityPermission;
 use BookStack\Auth\Permissions\JointPermission;
-use BookStack\Entities\Tools\SearchIndex;
+use BookStack\Auth\Permissions\JointPermissionBuilder;
+use BookStack\Auth\Permissions\PermissionApplicator;
 use BookStack\Entities\Tools\SlugGenerator;
-use BookStack\Facades\Permissions;
 use BookStack\Interfaces\Deletable;
 use BookStack\Interfaces\Favouritable;
 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;
@@ -39,11 +42,9 @@ 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()
- * @method static Entity|Builder hasPermission(string $permission)
  * @method static Builder withLastView()
  * @method static Builder withViewCount()
  */
@@ -68,15 +69,7 @@ abstract class Entity extends Model implements Sluggable, Favouritable, Viewable
      */
     public function scopeVisible(Builder $query): Builder
     {
-        return $this->scopeHasPermission($query, 'view');
-    }
-
-    /**
-     * Scope the query to those entities that the current user has the given permission for.
-     */
-    public function scopeHasPermission(Builder $query, string $permission)
-    {
-        return Permissions::restrictEntityQuery($query, $permission);
+        return app()->make(PermissionApplicator::class)->restrictEntityQuery($query);
     }
 
     /**
@@ -182,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;
     }
 
     /**
@@ -210,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'.
@@ -284,8 +292,7 @@ abstract class Entity extends Model implements Sluggable, Favouritable, Viewable
      */
     public function rebuildPermissions()
     {
-        /** @noinspection PhpUnhandledExceptionInspection */
-        Permissions::buildJointPermissionsForEntity(clone $this);
+        app()->make(JointPermissionBuilder::class)->rebuildForEntity(clone $this);
     }
 
     /**
@@ -293,7 +300,7 @@ abstract class Entity extends Model implements Sluggable, Favouritable, Viewable
      */
     public function indexForSearch()
     {
-        app(SearchIndex::class)->indexEntity(clone $this);
+        app()->make(SearchIndex::class)->indexEntity(clone $this);
     }
 
     /**
@@ -301,7 +308,7 @@ abstract class Entity extends Model implements Sluggable, Favouritable, Viewable
      */
     public function refreshSlug(): string
     {
-        $this->slug = app(SlugGenerator::class)->generate($this);
+        $this->slug = app()->make(SlugGenerator::class)->generate($this);
 
         return $this->slug;
     }

app/Entities/Models/Page.php

@@ -2,27 +2,31 @@
 
 namespace BookStack\Entities\Models;
 
+use BookStack\Auth\Permissions\PermissionApplicator;
 use BookStack\Entities\Tools\PageContent;
-use BookStack\Facades\Permissions;
 use BookStack\Uploads\Attachment;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
 
 /**
  * Class Page.
  *
- * @property int        $chapter_id
- * @property string     $html
- * @property string     $markdown
- * @property string     $text
- * @property bool       $template
- * @property bool       $draft
- * @property int        $revision_count
- * @property Chapter    $chapter
- * @property Collection $attachments
+ * @property int          $chapter_id
+ * @property string       $html
+ * @property string       $markdown
+ * @property string       $text
+ * @property bool         $template
+ * @property bool         $draft
+ * @property int          $revision_count
+ * @property string       $editor
+ * @property Chapter      $chapter
+ * @property Collection   $attachments
+ * @property Collection   $revisions
+ * @property PageRevision $currentRevision
  */
 class Page extends BookChild
 {
@@ -35,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',
@@ -47,7 +51,7 @@ class Page extends BookChild
      */
     public function scopeVisible(Builder $query): Builder
     {
-        $query = Permissions::enforceDraftVisibilityOnQuery($query);
+        $query = app()->make(PermissionApplicator::class)->restrictDraftsOnPageQuery($query);
 
         return parent::scopeVisible($query);
     }
@@ -82,6 +86,17 @@ class Page extends BookChild
             ->orderBy('id', 'desc');
     }
 
+    /**
+     * Get the current revision for the page if existing.
+     */
+    public function currentRevision(): HasOne
+    {
+        return $this->hasOne(PageRevision::class)
+            ->where('type', '=', 'version')
+            ->orderBy('created_at', 'desc')
+            ->orderBy('id', 'desc');
+    }
+
     /**
      * Get all revision instances assigned to this page.
      * Includes all types of revisions.
@@ -117,16 +132,6 @@ class Page extends BookChild
         return url('/' . implode('/', $parts));
     }
 
-    /**
-     * Get the current revision for the page if existing.
-     *
-     * @return PageRevision|null
-     */
-    public function getCurrentRevision()
-    {
-        return $this->revisions()->first();
-    }
-
     /**
      * Get this page for JSON display.
      */
@@ -138,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;
@@ -10,7 +11,9 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
 /**
  * Class PageRevision.
  *
+ * @property mixed  $id
  * @property int    $page_id
+ * @property string $name
  * @property string $slug
  * @property string $book_slug
  * @property int    $created_by
@@ -20,13 +23,15 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
  * @property string $summary
  * @property string $markdown
  * @property string $html
+ * @property string $text
  * @property int    $revision_number
  * @property Page   $page
  * @property-read ?User $createdBy
  */
-class PageRevision extends Model
+class PageRevision extends Model implements Loggable
 {
-    protected $fillable = ['name', 'html', 'text', 'markdown', 'summary'];
+    protected $fillable = ['name', 'text', 'summary'];
+    protected $hidden = ['html', 'markdown', 'text'];
 
     /**
      * Get the user that created the page revision.
@@ -79,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/Queries/EntityQuery.php

@@ -2,14 +2,14 @@
 
 namespace BookStack\Entities\Queries;
 
-use BookStack\Auth\Permissions\PermissionService;
+use BookStack\Auth\Permissions\PermissionApplicator;
 use BookStack\Entities\EntityProvider;
 
 abstract class EntityQuery
 {
-    protected function permissionService(): PermissionService
+    protected function permissionService(): PermissionApplicator
     {
-        return app()->make(PermissionService::class);
+        return app()->make(PermissionApplicator::class);
     }
 
     protected function entityProvider(): EntityProvider

app/Entities/Queries/Popular.php

@@ -7,10 +7,10 @@ use Illuminate\Support\Facades\DB;
 
 class Popular extends EntityQuery
 {
-    public function run(int $count, int $page, array $filterModels = null, string $action = 'view')
+    public function run(int $count, int $page, array $filterModels = null)
     {
         $query = $this->permissionService()
-            ->filterRestrictedEntityRelations(View::query(), 'views', 'viewable_id', 'viewable_type', $action)
+            ->restrictEntityRelationQuery(View::query(), 'views', 'viewable_id', 'viewable_type')
             ->select('*', 'viewable_id', 'viewable_type', DB::raw('SUM(views) as view_count'))
             ->groupBy('viewable_id', 'viewable_type')
             ->orderBy('view_count', 'desc');

app/Entities/Queries/RecentlyViewed.php

@@ -14,12 +14,11 @@ class RecentlyViewed extends EntityQuery
             return collect();
         }
 
-        $query = $this->permissionService()->filterRestrictedEntityRelations(
+        $query = $this->permissionService()->restrictEntityRelationQuery(
             View::query(),
             'views',
             'viewable_id',
-            'viewable_type',
-            'view'
+            'viewable_type'
         )
             ->orderBy('views.updated_at', 'desc')
             ->where('user_id', '=', user()->id);

app/Entities/Queries/TopFavourites.php

@@ -15,7 +15,7 @@ class TopFavourites extends EntityQuery
         }
 
         $query = $this->permissionService()
-            ->filterRestrictedEntityRelations(Favourite::query(), 'favourites', 'favouritable_id', 'favouritable_type', 'view')
+            ->restrictEntityRelationQuery(Favourite::query(), 'favourites', 'favouritable_id', 'favouritable_type')
             ->select('favourites.*')
             ->leftJoin('views', function (JoinClause $join) {
                 $join->on('favourites.favouritable_id', '=', 'views.viewable_id');

app/Entities/Repos/BaseRepo.php

@@ -6,18 +6,21 @@ 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;
 
 class BaseRepo
 {
-    protected $tagRepo;
-    protected $imageRepo;
+    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();
         }
 
@@ -58,10 +64,15 @@ class BaseRepo
 
         if (isset($input['tags'])) {
             $this->tagRepo->saveTagsToEntity($entity, $input['tags']);
+            $entity->touch();
         }
 
         $entity->rebuildPermissions();
         $entity->indexForSearch();
+
+        if ($oldUrl !== $entity->getUrl()) {
+            $this->referenceUpdater->updateEntityPageReferences($entity, $oldUrl);
+        }
     }
 
     /**
@@ -75,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/BookRepo.php

@@ -91,6 +91,7 @@ class BookRepo
     {
         $book = new Book();
         $this->baseRepo->create($book, $input);
+        $this->baseRepo->updateCoverImage($book, $input['image'] ?? null);
         Activity::add(ActivityType::BOOK_CREATE, $book);
 
         return $book;
@@ -102,6 +103,11 @@ class BookRepo
     public function update(Book $book, array $input): Book
     {
         $this->baseRepo->update($book, $input);
+
+        if (array_key_exists('image', $input)) {
+            $this->baseRepo->updateCoverImage($book, $input['image'], $input['image'] === null);
+        }
+
         Activity::add(ActivityType::BOOK_UPDATE, $book);
 
         return $book;

app/Entities/Repos/BookshelfRepo.php

@@ -6,12 +6,10 @@ use BookStack\Actions\ActivityType;
 use BookStack\Entities\Models\Book;
 use BookStack\Entities\Models\Bookshelf;
 use BookStack\Entities\Tools\TrashCan;
-use BookStack\Exceptions\ImageUploadException;
 use BookStack\Exceptions\NotFoundException;
 use BookStack\Facades\Activity;
 use Exception;
 use Illuminate\Contracts\Pagination\LengthAwarePaginator;
-use Illuminate\Http\UploadedFile;
 use Illuminate\Support\Collection;
 
 class BookshelfRepo
@@ -89,6 +87,7 @@ class BookshelfRepo
     {
         $shelf = new Bookshelf();
         $this->baseRepo->create($shelf, $input);
+        $this->baseRepo->updateCoverImage($shelf, $input['image'] ?? null);
         $this->updateBooks($shelf, $bookIds);
         Activity::add(ActivityType::BOOKSHELF_CREATE, $shelf);
 
@@ -106,14 +105,17 @@ class BookshelfRepo
             $this->updateBooks($shelf, $bookIds);
         }
 
+        if (array_key_exists('image', $input)) {
+            $this->baseRepo->updateCoverImage($shelf, $input['image'], $input['image'] === null);
+        }
+
         Activity::add(ActivityType::BOOKSHELF_UPDATE, $shelf);
 
         return $shelf;
     }
 
     /**
-     * Update which books are assigned to this shelf by
-     * syncing the given book ids.
+     * Update which books are assigned to this shelf by syncing the given book ids.
      * Function ensures the books are visible to the current user and existing.
      */
     protected function updateBooks(Bookshelf $shelf, array $bookIds)
@@ -132,42 +134,6 @@ class BookshelfRepo
         $shelf->books()->sync($syncData);
     }
 
-    /**
-     * Update the given shelf cover image, or clear it.
-     *
-     * @throws ImageUploadException
-     * @throws Exception
-     */
-    public function updateCoverImage(Bookshelf $shelf, ?UploadedFile $coverImage, bool $removeImage = false)
-    {
-        $this->baseRepo->updateCoverImage($shelf, $coverImage, $removeImage);
-    }
-
-    /**
-     * 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/DeletionRepo.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace BookStack\Entities\Repos;
+
+use BookStack\Actions\ActivityType;
+use BookStack\Entities\Models\Deletion;
+use BookStack\Entities\Tools\TrashCan;
+use BookStack\Facades\Activity;
+
+class DeletionRepo
+{
+    private TrashCan $trashCan;
+
+    public function __construct(TrashCan $trashCan)
+    {
+        $this->trashCan = $trashCan;
+    }
+
+    public function restore(int $id): int
+    {
+        /** @var Deletion $deletion */
+        $deletion = Deletion::query()->findOrFail($id);
+        Activity::add(ActivityType::RECYCLE_BIN_RESTORE, $deletion);
+
+        return $this->trashCan->restoreFromDeletion($deletion);
+    }
+
+    public function destroy(int $id): int
+    {
+        /** @var Deletion $deletion */
+        $deletion = Deletion::query()->findOrFail($id);
+        Activity::add(ActivityType::RECYCLE_BIN_DESTROY, $deletion);
+
+        return $this->trashCan->destroyFromDeletion($deletion);
+    }
+}