Merge pull request #959 from codeigniter4/develop

1.0.0-beta.8 Ready code

Author: kenjis

.github/workflows/docs.yml

@@ -9,11 +9,18 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
           python-version: 3.x
-      - run: pip3 install mkdocs-material
-      - run: pip3 install mkdocs-git-revision-date-localized-plugin
-      - run: pip3 install mkdocs-redirects
-      - run: mkdocs gh-deploy --force
+      - name: Install Dependencies
+        run: |
+          pip3 install mkdocs-material
+          pip3 install mkdocs-git-revision-date-localized-plugin
+          pip3 install mkdocs-redirects
+      - name: Publish Shiled Documentation
+        run: mkdocs gh-deploy --force

.github/workflows/no-merge-commits.yml

@@ -2,6 +2,8 @@ name: Detect Merge Commits
 
 on:
   pull_request:
+    branches:
+      - develop
 
 permissions:
   contents: read

.gitignore

@@ -64,6 +64,11 @@ phpunit
 vendor/
 composer.lock
 
+#-------------------------
+# MkDocs
+#-------------------------
+site/
+
 #-------------------------
 # IDE / Development Files
 #-------------------------

.php-cs-fixer.dist.php

@@ -2,6 +2,15 @@
 
 declare(strict_types=1);
 
+/**
+ * This file is part of CodeIgniter Shield.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
 use CodeIgniter\CodingStandard\CodeIgniter4;
 use Nexus\CsConfig\Factory;
 use PhpCsFixer\Finder;
@@ -28,4 +37,8 @@
     'cacheFile' => 'build/.php-cs-fixer.cache',
 ];
 
-return Factory::create(new CodeIgniter4(), $overrides, $options)->forProjects();
+return Factory::create(new CodeIgniter4(), $overrides, $options)->forLibrary(
+    'CodeIgniter Shield',
+    'CodeIgniter Foundation',
+    '[email protected]'
+);

README.md

@@ -58,7 +58,7 @@ and authorization purposes in web applications.
 * Flexible Groups-based access control (think Roles, but more flexible)
 * Users can be granted additional Permissions
 
-See the [An Official Auth Library](https://codeigniter.com/news/shield) for more Info.
+See the [An Official Auth Library](https://forum.codeigniter.com/showthread.php?tid=82003) for more Info.
 
 ## Getting Started
 

UPGRADING.md

@@ -1,5 +1,72 @@
 # Upgrade Guide
 
+## Version 1.0.0-beta.7 to 1.0.0-beta.8
+
+### Mandatory Config Changes
+
+#### Helper Autoloading
+
+Helper autoloading has been changed to be done by CodeIgniter's autoloader
+instead of Composer.
+
+So you need to update the settings. Run `php spark shield:setup` again, and the
+following steps will be done.
+
+1. Add `auth` and `setting` to the `$helpers` array in **app/Config/Autoload.php**:
+
+    ```php
+    public $helpers = ['auth', 'setting'];
+    ```
+
+2. Remove the following code in the `initController()` method in
+   `**app/Controllers/BaseController.php**:
+
+    ```php
+    $this->helpers = array_merge($this->helpers, ['setting']);
+    ```
+
+#### Config\Auth
+
+The following items have been added. Copy the properties in **src/Config/Auth.php**.
+
+- `permission_denied` and `group_denied` are added to `Config\Auth::$redirects`.
+- `permissionDeniedRedirect()` and `groupDeniedRedirect()` are added.
+
+### Fix Custom Filter If extends `AbstractAuthFilter`
+
+If you have written a custom filter that extends `AbstractAuthFilter`, now you need to add and implement the `redirectToDeniedUrl()` method to your custom filter.
+The following example is related to the above explanation for **group** filter.
+
+```php
+/**
+ * If the user does not belong to the group, redirect to the configured URL with an error message.
+ */
+protected function redirectToDeniedUrl(): RedirectResponse
+{
+    return redirect()->to(config('Auth')->groupDeniedRedirect())
+        ->with('error', lang('Auth.notEnoughPrivilege'));
+}
+```
+
+### Fix to HMAC Secret Key Encryption
+
+#### Config\AuthToken
+
+If you are using the HMAC authentication you need to update the encryption settings in **app/Config/AuthToken.php**.
+You will need to update and set the encryption key in `$hmacEncryptionKeys`. This should be set using **.env** and/or
+system environment variables. Instructions on how to do that can be found in the
+[Setting Your Encryption Key](https://codeigniter.com/user_guide/libraries/encryption.html#setting-your-encryption-key)
+section of the CodeIgniter 4 documentation and in [HMAC SHA256 Token Authenticator](./docs/references/authentication/hmac.md#hmac-secret-key-encryption).
+
+You also may wish to adjust the default Driver `$hmacEncryptionDefaultDriver` and the default Digest
+`$hmacEncryptionDefaultDigest`, these currently default to `'OpenSSL'` and `'SHA512'` respectively.
+
+#### Encrypt Existing Keys
+
+After updating the key in `$hmacEncryptionKeys` value, you will need to run `php spark shield:hmac encrypt` in order
+to encrypt any existing HMAC tokens. This only needs to be run if you have existing unencrypted HMAC secretKeys in
+stored in the database.
+
 ## Version 1.0.0-beta.6 to 1.0.0-beta.7
 
 ### The minimum CodeIgniter version

admin/RELEASE.md

@@ -36,41 +36,43 @@ the changelog.
 
 ## Preparation
 
-* Clone **codeigniter4/shield** and resolve any necessary PRs
+* [ ] Clone **codeigniter4/shield** and resolve any necessary PRs
     ```console
     git clone [email protected]:codeigniter4/shield.git
     ```
-* Merge any Security Advisory PRs in private forks
+* [ ] Merge any Security Advisory PRs in private forks
 
 ## Process
 
 > **Note** Most changes that need noting in the User Guide and docs should have
 > been included with their PR, so this process assumes you will not be
 > generating much new content.
 
-* Create a new branch `release-1.x.x`
-* Update **src/Auth.php** with the new version number:
+* [ ] Create a new branch `release-1.x.x`
+* [ ] Update **src/Auth.php** with the new version number:
   `const SHIELD_VERSION = '1.x.x';`
-* Commit the changes with "Prep for 1.x.x release" and push to origin
-* Create a new PR from `release-1.x.x` to `develop`:
+* [ ] Commit the changes with "Prep for 1.x.x release" and push to origin
+* [ ] Create a new PR from `release-1.x.x` to `develop`:
     * Title: "Prep for 1.x.x release"
     * Description: "Updates version references for `1.x.x`." (plus checklist)
-* Let all tests run, then review and merge the PR
-* Create a new PR from `develop` to `master`:
+* [ ] Let all tests run, then review and merge the PR
+* [ ] Create a new PR from `develop` to `master`:
     * Title: "1.x.x Ready code"
     * Description: blank
-* Merge the PR
-* Create a new Release:
+* [ ] Merge the PR
+* [ ] Create a new Release:
     * Version: "v1.x.x"
     * Target: master
     * Title: "v1.x.x"
     * Click the "Generate release notes" button
     * Remove "### Others (Only for checking. Remove this category)" section
+    * Add important notes if necessary
+    * Add link to Upgrade Guide if necessary
     * Check "Create a discussion for this release"
     * Click the "Publish release" button
-* Watch for the "docs" action and verify that the user guide updated:
+* [ ] Watch for the "docs" action and verify that the user guide updated:
     * [docs](https://github.com/codeigniter4/shield/actions/workflows/docs.yml)
-* Fast-forward `develop` branch to catch the merge commit from `master`
+* [ ] Fast-forward `develop` branch to catch the merge commit from `master`
   (note: pushing to `develop` is restricted to administrators):
     ```console
     git fetch origin
@@ -82,9 +84,9 @@ the changelog.
   **At this point, `master` must be merged into `develop`.** Otherwise, the
   GitHub-generated release note from `develop` for the next release will not be
   generated correctly.
-* Publish any Security Advisories that were resolved from private forks
+* [ ] Publish any Security Advisories that were resolved from private forks
   (note: publishing is restricted to administrators)
-* Announce the release on the forums and Slack channel
+* [ ] Announce the release on the forums and Slack channel
   (note: this forum is restricted to administrators):
     * Make a new topic in the "News & Discussion" forums:
       https://forum.codeigniter.com/forum-2.html

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.5"
+        "rector/rector": "0.18.10"
     },
     "provide": {
         "codeigniter4/authentication-implementation": "1.0"
@@ -52,9 +52,6 @@
         "psr-4": {
             "CodeIgniter\\Shield\\": "src"
         },
-        "files": [
-            "src/Helpers/auth_helper.php"
-        ],
         "exclude-from-classmap": [
             "**/Database/Migrations/**"
         ]

docs/addons/jwt.md

@@ -33,9 +33,10 @@ To use JWT Authentication, you need additional setup and configuration.
 2. Copy the **AuthJWT.php** from **vendor/codeigniter4/shield/src/Config/** into your project's config folder and update the namespace to `Config`. You will also need to have these classes extend the original classes. See the example below.
 
     ```php
-    // new file - app/Config/AuthJWT.php
     <?php
 
+    // app/Config/AuthJWT.php
+
     declare(strict_types=1);
 
     namespace Config;
@@ -127,6 +128,19 @@ php -r 'echo base64_encode(random_bytes(32));'
 
     The secret key is used for signing and validating tokens.
 
+### Login Attempt Logging
+
+By default, only failed login attempts are recorded in the `auth_token_logins` table.
+
+```php
+public int $recordLoginAttempt = Auth::RECORD_LOGIN_ATTEMPT_FAILURE;
+```
+
+If you don't want any logs, set it to `Auth::RECORD_LOGIN_ATTEMPT_NONE`.
+
+If you want to log all login attempts, set it to `Auth::RECORD_LOGIN_ATTEMPT_ALL`.
+It means you log all requests.
+
 ## Issuing JWTs
 
 To use JWT Authentication, you need a controller that issues JWTs.
@@ -140,7 +154,10 @@ $routes->post('auth/jwt', '\App\Controllers\Auth\LoginController::jwtLogin');
 ```
 
 ```php
+<?php
+
 // app/Controllers/Auth/LoginController.php
+
 declare(strict_types=1);
 
 namespace App\Controllers\Auth;
@@ -260,6 +277,7 @@ file itself:
 $routes->group('api', ['filter' => 'jwt'], static function ($routes) {
     // ...
 });
+
 $routes->get('users', 'UserController::list', ['filter' => 'jwt']);
 ```
 
@@ -346,3 +364,14 @@ It uses the `secret` and `alg` in the `Config\AuthJWT::$keys['default']`.
 It sets the `Config\AuthJWT::$defaultClaims` to the token, and sets
 `"iat"` (Issued At) and `"exp"` (Expiration Time) claims automatically even if
 you don't pass them.
+
+## Logging
+
+Login attempts are recorded in the `auth_token_logins` table, according to the
+configuration above.
+
+When a failed login attempt is logged, the raw token value sent is saved in
+the `identifier` column.
+
+When a successful login attempt is logged, the SHA256 hash value of the token
+sent is saved in the `identifier` column.