Merge pull request #992 from codeigniter4/develop

1.0.0 Ready code

.github/workflows/docs.yml

@@ -14,7 +14,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - name: Install Dependencies

UPGRADING.md

@@ -1,5 +1,13 @@
 # Upgrade Guide
 
+## Version 1.0.0-beta.8 to 1.0.0
+
+## Removed Deprecated Items
+
+The [$supportOldDangerousPassword](#if-you-want-to-allow-login-with-existing-passwords)
+feature for backward compatiblity has been removed. The old passwords saved in
+Shield v1.0.0-beta.3 or earlier are no longer supported.
+
 ## Version 1.0.0-beta.7 to 1.0.0-beta.8
 
 ### Mandatory Config Changes

admin/RELEASE.md

@@ -38,6 +38,8 @@ the changelog.
 
 * [ ] Clone **codeigniter4/shield** and resolve any necessary PRs
     ```console
+    rm -rf shield.bk
+    mv shield shield.bk
     git clone [email protected]:codeigniter4/shield.git
     ```
 * [ ] Merge any Security Advisory PRs in private forks

composer.json

@@ -37,7 +37,7 @@
         "mockery/mockery": "^1.0",
         "phpstan/extension-installer": "^1.3",
         "phpstan/phpstan-strict-rules": "^1.5",
-        "rector/rector": "0.18.10"
+        "rector/rector": "0.18.13"
     },
     "provide": {
         "codeigniter4/authentication-implementation": "1.0"

docs/CNAME

@@ -0,0 +1 @@
+shield.codeigniter.com

docs/assets/css/codeigniter.css

@@ -0,0 +1,18 @@
+[data-md-color-scheme="codeigniter"] {
+    --md-primary-fg-color:        #dd4814;
+    --md-primary-fg-color--light: #ECB7B7;
+    --md-primary-fg-color--dark:  #90030C;
+
+    --md-default-bg-color: #fcfcfc;
+
+    --md-typeset-a-color: #e74c3c;
+    --md-accent-fg-color: #97310e;
+
+    --md-accent-fg-color--transparent: #ECB7B7;
+
+    --md-code-bg-color: #ffffff;
+
+    .md-typeset code {
+        border: 1px solid #e1e4e5;
+    }
+}

docs/assets/css/dark_mode.css → docs/assets/css/codeigniter_dark_mode.css

@@ -1,8 +1,17 @@
 [data-md-color-scheme="slate"] {
-    --md-primary-fg-color: #6a290d;
+    --md-primary-fg-color: #b13a10;
     --md-primary-fg-color--light: #8d7474;
     --md-primary-fg-color--dark: #6d554d;
 
+    --md-default-bg-color: #1e2129;
+
+    --md-typeset-a-color: #ed6436;
+    --md-accent-fg-color: #f18a67;
+
+    --md-accent-fg-color--transparent: #625151;
+
+    --md-code-bg-color: #282b2d;
+
     .hljs-title,
     .hljs-title.class_,
     .hljs-title.class_.inherited__,
@@ -43,31 +52,30 @@
         color: #ddba52
     }
 
-    .md-typeset .note > .admonition-title,
-    .md-typeset .note > summary {
-        background-color: #0000001a;
+    .md-typeset code {
+        border: 1px solid #3f4547;
     }
 
     .md-typeset .admonition.note,
     .md-typeset details.note {
-        border-color: #675647;
+        border-color: #2c5293;
     }
 
     .md-typeset .note > .admonition-title:before,
     .md-typeset .note > summary:before {
-        background-color: #65686d;
+        background-color: #2c5293;
         -webkit-mask-image: var(--md-admonition-icon--note);
         mask-image: var(--md-admonition-icon--note);
     }
 
     .md-typeset .admonition.warning,
     .md-typeset details.warning {
-        border-color: #776144;
+        border-color: #97631e;
     }
 
     .md-typeset .warning > .admonition-title:before,
     .md-typeset .warning > summary:before {
-        background-color: #d9913bc2;
+        background-color: #97631e;
         -webkit-mask-image: var(--md-admonition-icon--warning);
         mask-image: var(--md-admonition-icon--warning);
     }

docs/assets/js/hljs.js

@@ -1,3 +1,3 @@
-document.addEventListener('DOMContentLoaded', (event) => {
+window.document$.subscribe(() => {
     hljs.highlightAll();
 });

docs/customization/adding_attributes_to_users.md

@@ -74,6 +74,8 @@ php spark db:table users
 
 See [Customizing User Provider](./user_provider.md).
 
+Don't forget to add the added attributes to the `$allowedFields` property.
+
 ## Update Validation Rules
 
 You need to update the [validation rules](./validation_rules.md) for registration.

docs/customization/route_config.md

@@ -19,6 +19,16 @@ $routes->get('register', '\App\Controllers\Auth\RegisterController::registerView
 
 After customization, check your routes with the [spark routes](https://codeigniter.com/user_guide/incoming/routing.html#spark-routes) command.
 
+## Change Namespace
+
+If you are overriding all of the auth controllers, you can specify the namespace as an option to the `routes()` helper:
+
+```php
+service('auth')->routes($routes, ['namespace' => '\App\Controllers\Auth']);
+```
+
+This will generate the routes with the specified namespace instead of the default Shield namespace. This can be combined with any other options, like `except`.
+
 ## Use Locale Routes
 
 You can use the `{locale}` placeholder in your routes

docs/customization/user_provider.md

@@ -1,5 +1,7 @@
 # Customizing User Provider
 
+## Creating Your Own UserModel
+
 If you want to customize user attributes, you need to create your own
 [User Provider](../getting_started/concepts.md#user-providers) class.
 The only requirement is that your new class MUST extend the provided `CodeIgniter\Shield\Models\UserModel`.
@@ -13,8 +15,42 @@ php spark shield:model UserModel
 
 The class name is optional. If none is provided, the generated class name would be `UserModel`.
 
-After creating the class, set the `$userProvider` property in **app/Config/Auth.php** as follows:
+## Configuring to Use Your UserModel
+
+After creating the class, set your model classname to the `$userProvider` property
+in **app/Config/Auth.php**:
 
 ```php
 public string $userProvider = \App\Models\UserModel::class;
 ```
+
+## Customizing Your UserModel
+
+Customize your model as you like.
+
+If you add attributes, don't forget to add the attributes to the `$allowedFields`
+property.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use CodeIgniter\Shield\Models\UserModel as ShieldUserModel;
+
+class UserModel extends ShieldUserModel
+{
+    protected function initialize(): void
+    {
+        parent::initialize();
+
+        $this->allowedFields = [
+            ...$this->allowedFields,
+            'first_name', // Added
+            'last_name',  // Added
+        ];
+    }
+}
+```

docs/index.md

@@ -1,40 +1,40 @@
 # Shield Documentation
 
-## What is Shield? 🤔
+## What is Shield?
 
 Shield is the official authentication and authorization framework for CodeIgniter 4. While
 it does provide a base set of tools that are commonly used in websites, it is
 designed to be flexible and easily customizable.
 
-### Primary Goals 🥅
+### Primary Goals
 
 The primary goals for Shield are:
 
 1. It must be very flexible and allow developers to extend/override almost any part of it.
 2. It must have security at its core. It is an auth lib after all.
 3. To cover many auth needs right out of the box, but be simple to add additional functionality to.
 
-### Important Features 🌠
+### Important Features
 
-* **Session-based Authentication** (traditional **ID/Password** with **Remember-me**)
-* **Stateless Authentication** using **Access Token**, **HMAC SHA256 Token**, or **JWT**
-* Optional **Email verification** on account registration
-* Optional **Email-based Two-Factor Authentication** after login
-* **Magic Link Login** when a user forgets their password
-* Flexible **Group-based Access Control** (think Roles, but more flexible), and users can be granted additional **Permissions**
-* A simple **Auth Helper** that provides access to the most common auth actions
-* Save initial settings in your code, so it can be in version control, but can also be updated in the database, thanks to our [Settings](https://github.com/codeigniter4/settings) library
-* Highly configurable
-* **User Entity** and **User Provider** (`UserModel`) ready for you to use or extend
-* Built to extend and modify
-    * Easily extendable controllers
-    * All required views that can be used as is or swapped out for your own
+-   **Session-based Authentication** (traditional **ID/Password** with **Remember-me**)
+-   **Stateless Authentication** using **Access Token**, **HMAC SHA256 Token**, or **JWT**
+-   Optional **Email verification** on account registration
+-   Optional **Email-based Two-Factor Authentication** after login
+-   **Magic Link Login** when a user forgets their password
+-   Flexible **Group-based Access Control** (think Roles, but more flexible), and users can be granted additional **Permissions**
+-   A simple **Auth Helper** that provides access to the most common auth actions
+-   Save initial settings in your code, so it can be in version control, but can also be updated in the database, thanks to our [Settings](https://github.com/codeigniter4/settings) library
+-   Highly configurable
+-   **User Entity** and **User Provider** (`UserModel`) ready for you to use or extend
+-   Built to extend and modify
+    -   Easily extendable controllers
+    -   All required views that can be used as is or swapped out for your own
 
-### License 📑
+### License
 
 Shield is licensed under the MIT License - see the [LICENSE](https://github.com/codeigniter4/shield/blob/develop/LICENSE) file for details.
 
-### Acknowledgements 🙌🏼
+### Acknowledgements
 
 Every open-source project depends on it's contributors to be a success. The following users have
 contributed in one manner or another in making Shield:
@@ -48,7 +48,7 @@ Made with [contrib.rocks](https://contrib.rocks).
 The following articles/sites have been fundamental in shaping the security and best practices used
 within this library, in no particular order:
 
-- [Google Cloud: 13 best practices for user account, authentication, and password management, 2021 edition](https://cloud.google.com/blog/products/identity-security/account-authentication-and-password-management-best-practices)
-- [NIST Digital Identity Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html)
-- [Implementing Secure User Authentication in PHP Applications with Long-Term Persistence (Login with "Remember Me" Cookies) ](https://paragonie.com/blog/2015/04/secure-authentication-php-with-long-term-persistence)
-- [Password Storage - OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+-   [Google Cloud: 13 best practices for user account, authentication, and password management, 2021 edition](https://cloud.google.com/blog/products/identity-security/account-authentication-and-password-management-best-practices)
+-   [NIST Digital Identity Guidelines](https://pages.nist.gov/800-63-3/sp800-63b.html)
+-   [Implementing Secure User Authentication in PHP Applications with Long-Term Persistence (Login with "Remember Me" Cookies) ](https://paragonie.com/blog/2015/04/secure-authentication-php-with-long-term-persistence)
+-   [Password Storage - OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)

mkdocs.yml

@@ -12,23 +12,22 @@ theme:
   palette:
     # Palette toggle for light mode
     - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: deep orange
-      accent: orange
+      scheme: codeigniter
+      primary: custom
+      accent: custom
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
     # Palette toggle for dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
-      primary: deep orange
-      accent: orange
+      primary: custom
+      accent: custom
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
   features:
     - navigation.instant
-    - navigation.instant.prefetch
     - content.code.copy
     - navigation.footer
     - content.action.edit
@@ -55,7 +54,7 @@ extra:
       link: https://join.slack.com/t/codeigniterchat/shared_invite/zt-244xrrslc-l_I69AJSi5y2a2RVN~xIdQ
       name: Slack
 
-
+site_url: https://shield.codeigniter.com/
 repo_url: https://github.com/codeigniter4/shield
 edit_uri: edit/develop/docs/
 copyright: Copyright © 2023 CodeIgniter Foundation.
@@ -68,8 +67,9 @@ markdown_extensions:
   - pymdownx.details
 
 extra_css:
-  - https://cdn.jsdelivr.net/gh/highlightjs/[email protected]/build/styles/default.min.css
-  - assets/css/dark_mode.css
+  - https://cdn.jsdelivr.net/gh/highlightjs/[email protected]/build/styles/github.min.css
+  - assets/css/codeigniter.css
+  - assets/css/codeigniter_dark_mode.css
 
 extra_javascript:
   - https://cdn.jsdelivr.net/gh/highlightjs/[email protected]/build/highlight.min.js

phpstan-baseline.php

@@ -311,31 +311,11 @@
 	'count' => 1,
 	'path' => __DIR__ . '/src/Models/UserIdentityModel.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Cannot unset offset \'email\' on array\\{username\\: string, status\\: string, status_message\\: string, active\\: bool, last_active\\: string, deleted_at\\: string\\}\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/src/Models/UserModel.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Cannot unset offset \'password_hash\' on array\\{username\\: string, status\\: string, status_message\\: string, active\\: bool, last_active\\: string, deleted_at\\: string\\}\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/src/Models/UserModel.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Construct empty\\(\\) is not allowed\\. Use more strict comparison\\.$#',
 	'count' => 2,
 	'path' => __DIR__ . '/src/Models/UserModel.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Offset \'email\' does not exist on array\\{username\\: string, status\\: string, status_message\\: string, active\\: bool, last_active\\: string, deleted_at\\: string\\}\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/src/Models/UserModel.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Offset \'password_hash\' does not exist on array\\{username\\: string, status\\: string, status_message\\: string, active\\: bool, last_active\\: string, deleted_at\\: string\\}\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/src/Models/UserModel.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Parameter \\#1 \\$data \\(array\\|CodeIgniter\\\\Shield\\\\Entities\\\\User\\) of method CodeIgniter\\\\Shield\\\\Models\\\\UserModel\\:\\:insert\\(\\) should be contravariant with parameter \\$data \\(array\\|object\\|null\\) of method CodeIgniter\\\\Model\\:\\:insert\\(\\)$#',
 	'count' => 1,
@@ -368,7 +348,7 @@
 ];
 $ignoreErrors[] = [
 	'message' => '#^Call to method PHPUnit\\\\Framework\\\\Assert\\:\\:assertInstanceOf\\(\\) with \'CodeIgniter\\\\\\\\Shield\\\\\\\\Result\' and CodeIgniter\\\\Shield\\\\Result will always evaluate to true\\.$#',
-	'count' => 9,
+	'count' => 8,
 	'path' => __DIR__ . '/tests/Authentication/Authenticators/SessionAuthenticatorTest.php',
 ];
 $ignoreErrors[] = [

src/Auth.php

@@ -41,7 +41,7 @@ class Auth
     /**
      * The current version of CodeIgniter Shield
      */
-    public const SHIELD_VERSION = '1.0.0-beta.8';
+    public const SHIELD_VERSION = '1.0.0';
 
     protected AuthConfig $config;
     protected ?Authentication $authenticate = null;
@@ -138,7 +138,9 @@ public function routes(RouteCollection &$routes, array $config = []): void
     {
         $authRoutes = config('AuthRoutes')->routes;
 
-        $routes->group('/', ['namespace' => 'CodeIgniter\Shield\Controllers'], static function (RouteCollection $routes) use ($authRoutes, $config): void {
+        $namespace = $config['namespace'] ?? 'CodeIgniter\Shield\Controllers';
+
+        $routes->group('/', ['namespace' => $namespace], static function (RouteCollection $routes) use ($authRoutes, $config): void {
             foreach ($authRoutes as $name => $row) {
                 if (! isset($config['except']) || ! in_array($name, $config['except'], true)) {
                     foreach ($row as $params) {