4.x

Author: DarkGhostHunter

.github/workflows/php.yml

@@ -54,16 +54,13 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - 8.2
           - 8.3
           - 8.4
+          - 8.5
         laravel-constraint:
-          - 11.*
           - 12.*
+          - 13.*
         dependencies: [ lowest, highest ]
-        exclude:
-          - laravel-constraint: 12.*
-            php-version: 8.2
 
     steps:
       - name: Set up PHP

DATABASE.md

@@ -1,50 +1,44 @@
 # Model customization
 
-You can further customize the package Models using the `customize()` method with a callback that receives the freshly instanced model instance. For example, you may want to hide some attributes, or change the table and connection the Model by default. Preferably, you would do this in your `bootstrap/app.php`.
+Most of the time you will want to change the table name of the Model, maybe because it collides with another. Use the `customize()` method with the table name. Preferably, you would do this in your `bootstrap/app.php`.
 
 ```php
 use Illuminate\Foundation\Application;
-use Illuminate\Foundation\Configuration\Exceptions;
-use Illuminate\Foundation\Configuration\Middleware;
-use Vendor\Package\Models\Driver;
+use Vendor\Package\Models\Car;
 
 return Application::configure(basePath: dirname(__DIR__))
     ->booted(function () {
-        // Customize the model
-        Car::customize(function (Car $model) {
-            $model->setTable('my_custom_car');
-            $model->setConnection('readonly-mysql');
-            
-            $model->setHidden('private_notes');
-        })
+        // Customize the model table name.
+        Car::customize('vehicles');
     })->create();
 ```
 
-> [!TIP]
->
-> For your convenience, the Migration will automatically pick up the table and connection you set in the Model.
-
-## Changing the table name
+You can further customize the Models included in this package with a callback that receives a Model instance. This method is always executed when instancing a Model.
 
-To change the table the model should use, use the customize method inside the `->booted(...)` callback in `bootstrap/app.php` or within the `boot` method of a `ServiceProvider`.
+For example, you may hide some attributes or change the table and connection the Model by default.
 
 ```php
-TwoFactorAuthentication::customize(function (TwoFactorAuthentication $model) {
-    $model->setTable('my_custom_table');
+use Vendor\Package\Models\Car;
+
+Car::customize(function (Car $model) {
+    $model->setTable('vehicles');
+    $model->setConnection('readonly-mysql');
+            
+    $model->setHidden('private_notes');
 });
 ```
 
-> [!NOTE]
+> [!TIP]
+>
+> There is no need to alter the Model migration if you change the table. The migration automatically picks up the table and connection you set in through the `customize()` method.
 >
-> If you're migrating from 2.x to 3.x, the property `TwoFactorAuthentication::$useTable = 'my_custom_table';` is deprecated. Instead, set the custom table name using the `customize` method as shown above.
-
 
 # Migration customization
 
 The library you have installed comes with a very hands-off approach for migrations. If you check the new migrations published at `database/migrations`, you will find something very similar to this:
 
 ```php
-// database/migrations/2022_01_01_193000_create_cars_migration.php
+// database/migrations/2027_01_01_193000_create_cars_table.php
 use Vendor\Package\Models\Car;
 
 return Car::migration();
@@ -54,7 +48,7 @@ Worry not, the migration will still work. It has been _simplified_ for easy cust
 
 ## Adding columns
 
-To add columns to the migration, add a callback to the `with()` method. The callback will receive the table blueprint so you can modify the table while it's being created.
+To add columns to the migration, add a callback to the `with()` method. The callback will receive the table blueprint, so you can modify the table before it is created. New columns will be appended to the table blueprint.
 
 ```php
 use Illuminate\Database\Schema\Blueprint;
@@ -66,50 +60,45 @@ return Car::migration()->with(function (Blueprint $table) {
 });
 ```
 
-> [!NOTE]
->
-> The columns you add will be created _after_ the package adds its own columns. In other words, these will be set at the end of the table.
-
 ### Relationships
 
-If the package supports it, you may add relationships through their proper migration columns. For example, if we want to add the `driver` relationship to the model, we can use the native `resolveRelationUsing()` on your `bootstrap/app.php()`.
+If the package supports it, you may add relationships through their proper migration columns. For example, if we want to add the `car` relationship to the package Model, we can use the native `resolveRelationUsing()` on your `bootstrap/app.php()`.
 
 ```php
+use App\Models\Driver;
 use Illuminate\Foundation\Application;
-use Illuminate\Foundation\Configuration\Exceptions;
-use Illuminate\Foundation\Configuration\Middleware;
-use Vendor\Package\Models\Driver;
+use Vendor\Package\Models\Car;
 
 return Application::configure(basePath: dirname(__DIR__))
     ->booted(function () {
         // Add the relationship.
-        Car::resolveRelationUsing('driver', function (Car $car) {
-            return $car->belongsTo(Driver::class, 'driver_id')
+        Car::resolveRelationUsing('driver', function (Driver $driver) {
+            return $driver->belongsTo(Driver::class, 'driver_id');
         })
     })->create();
 ```
 
-In the published package migration, you should be able to add the required column to connect your model like normal. In this case, we can use the [`foreignIdFor()`](https://laravel.com/docs/migrations#column-method-foreignIdFor) method to safely set the proper column type.
+In the published package migration, you should be able to add the required column to connect your model like usual. In this case, we can use the [`foreignIdFor()`](https://laravel.com/docs/migrations#column-method-foreignIdFor) method to safely set the proper column name and type.
 
 ```php
 use App\Models\Driver;
 use Illuminate\Database\Schema\Blueprint;
-use Laragear\Package\Models\Car;
+use Vendor\Package\Models\Car;
 
-return Car::migration(function (Blueprint $table) {
+return Car::migration()->with(function (Blueprint $table) {
     // ...
 
-    $table->foreignIdFor(Driver::class);
+    $table->foreignIdFor(Driver::class, 'driver_id');
 });
 ```
 
 ## After Up & Before Down
 
-If you need to execute logic after creating the table, or before dropping it, use the `afterUp()` and `beforeDown()` methods, respectively.
+If you need to execute logic _after_ creating the table, or _before_ dropping it, use the `afterUp()` and `beforeDown()` methods, respectively.
 
 ```php
 use Illuminate\Database\Schema\Blueprint;
-use Laragear\Package\Models\Car;
+use Vendor\Package\Models\Car;
 
 return Car::migration()
     ->afterUp(function (Blueprint $table) {
@@ -120,27 +109,25 @@ return Car::migration()
     });
 ```
 
-## Morphs
+### Morphs
 
-This package _may_ create a morph relation automatically, with the intent to easily handle default relationship across multiple models. For example, a morph migration to support an `owner` being either one of your models `Company` or `Person`.
+Some packages will create a morph relation automatically to easily handle the default relationship across multiple models. For example, a morph migration to support an `owner` being either one of your models `user` or `business`.
 
 ```php
-use Laragear\Package\Models\Car;
+use Vendor\Package\Models\Car;
 
 $car = Car::find(1);
 
-$owners = $car->owner; // App/Models/Company or App/Models/Person
+$owner = $driver->owner; // App/Models/User or App/Models/Business
 ```
 
-You may find yourself with youur models using a primary key type, different to the type used by the library models. For example, your `Company` or `Person` models using UUID, while the migration morph type uses integers.
+You may find yourself with models that use UUID, ULID or other types of primary keys, but with a migration that creates morphs for integer primary keys.
 
-If that's your case, you can change the library morph type with the `morph...` property access (preferably), or the `morph()` method with `numeric`, `uuid` or `ulid` if you need to also set an index name (in case your database engine doesn't play nice with large ones).
-
-For example, you can change the morph type of the `Car` migration to match the UUID type for the `Company` and `Person` models.
+You can change the morph type with the `morph...` property access preferably, or the `morph()` method with `numeric`, `uuid` or `ulid` if you need to also set an index name (in case your database engine doesn't play nice with large ones).
 
 ```php
 use Illuminate\Database\Schema\Blueprint;
-use Laragear\Package\Models\Car;
+use Vendor\Package\Models\Car;
 
 return Car::migration()->morphUuid;
 

README.md

@@ -38,13 +38,16 @@ Your support allows me to keep this package free, up-to-date and maintainable. A
 
 ## Requirements
 
-* Laravel 11 or later
+* PHP 8.3 or later
+* Laravel 12 or later
 
 ## Installation
 
 Fire up Composer and require this package in your project.
 
-    composer require laragear/two-factor
+```shell
+composer require laragear/two-factor
+```
 
 That's it.
 
@@ -105,9 +108,9 @@ To enable Two-Factor Authentication for the User, he must sync the Shared Secret
 
 > [!TIP]
 >
-> Free Authenticator Apps, in no particular order, are [iOS Authenticator](https://www.apple.com/ios/), [FreeOTP](https://freeotp.github.io/), [Authy](https://authy.com/), [2FAS](https://2fas.com/), [2Stable Authenticator](https://authenticator.2stable.com/), [Step-two](https://steptwo.app/), [BinaryRoot Authenticator](https://www.binaryboot.com/totp-authenticator), [Google](https://apps.apple.com/app/google-authenticator/id388497605) [Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en), and [Microsoft Authenticator](https://www.microsoft.com/en-us/account/authenticator), to name a few.
+> Free Authenticator Apps, in no particular order, are [iOS Authenticator](https://www.apple.com/ios/), [FreeOTP](https://freeotp.github.io/), [Authy](https://authy.com/), [2FAS](https://2fas.com/), [2Stable Authenticator](https://authenticator.2stable.com/), [Step-two](https://steptwo.app/), [BinaryRoot Authenticator](https://www.binaryboot.com/totp-authenticator) and [Google](https://apps.apple.com/app/google-authenticator/id388497605) [Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en).
 
-To start, generate the needed data using the `createTwoFactorAuth()` method. This returns a serializable _Shared Secret_ that you can show to the User as a string or QR Code (encoded as SVG) in your view.
+To start, generate the necessary data using the `createTwoFactorAuth()` method. This returns a serializable _Shared Secret_ that you can show to the User as a string or QR Code (encoded as SVG) in your view.
 
 ```php
 use Illuminate\Http\Request;
@@ -406,6 +409,109 @@ Route::get('api/important-token', function () {
 })->middleware('2fa.require', '2fa.confirm:my-redirect-route-name,true');
 ```
 
+### Throttling Middleware
+
+This library includes a global throttling middleware. It will trigger a TOTP confirmation once a number of Requests done to the application exceed a default threshold. 
+
+To enable the global middleware, set the `OTP_THROTTLE` environment variable to `true`.
+
+```dotenv
+OTP_THROTTLE
+```
+
+Alternatively, you can enable it globally and also set the threshold using `{tries},{decay}` notation. For example, to change the threshold to a maximum of 3 requests each 15 seconds.
+
+```dotenv
+OTP_THROTTLE=3,15
+```
+
+You may configure the global throttling additional features in the [configuration file](#throttling).
+
+> [!IMPORTANT]
+> 
+> The Throttling Middleware uses your application [Rate Limiter](https://laravel.com/docs/12.x/rate-limiting).
+
+#### Using a custom throttle key
+
+By default, the key to throttle the request is generated using the IP.
+
+You may want to create your own key based on the request by setting a callback in the `$key` static property of the  `Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor` class, in your `bootstrap/app.php` file. For example, you may add a string to differentiate multiple users from the same IP. 
+
+```php
+use Illuminate\Foundation\Application;
+use Illuminate\Http\Request;
+use Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor;
+
+return Application::configure()
+    ->booted(function () {
+        ThrottleWithTwoFactor::$key = function (Request $request) {
+            return $request->ip() . '|' . $request->user()->getKey(); 
+        }
+    })
+    ->create();
+```
+
+#### Determining if the request should be throttled
+
+You may programmatically throttle requests by setting a callback in the `$shouldThrottle` static property of the  `Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor` class, in your `bootstrap/app.php` file.
+
+```php
+use Illuminate\Foundation\Application;
+use Illuminate\Http\Request;
+use Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor;
+
+return Application::configure()
+    ->booted(function () {
+        ThrottleWithTwoFactor::$shouldThrottle = function (Request $request) {
+            return $request->user()->isNotVip(); 
+        }
+    })
+    ->create();
+```
+
+Inside the function, you can use the method `clearAttempts()` of the middleware instance present as a second parameter in the callback to clear the attempts of the given request.
+
+```php
+use Illuminate\Foundation\Application;
+use Illuminate\Http\Request;
+use Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor;
+
+return Application::configure()
+    ->booted(function () {
+        ThrottleWithTwoFactor::$shouldThrottle = function (Request $request, ThrottleWithTwoFactor $instance) {
+            if ($request->user()->impersontedByAdmin()) {
+                $instance->clearAttempts($request);
+            }
+        
+            return $request->user()->isNotVip(); 
+        }
+    })
+    ->create();
+```
+
+
+#### Custom Rate Limiter Cache
+
+You may want to use a custom Cache Store to use with the middleware. This requires instructing the Container to give a custom Rate Limiter created by you when resolving the `Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor` class.
+
+This can be done in the `bootstrap/app.php` with the `registered()` method and [Contextual Binding](https://laravel.com/docs/12.x/container#contextual-binding).
+
+```php
+use Illuminate\Cache\RateLimiter;
+use Illuminate\Foundation\Application;
+use Laragear\TwoFactor\Http\Middleware\ThrottleWithTwoFactor;
+
+return Application::configure()
+    ->registered(function (Application $app) {
+        $app->when(ThrottleWithTwoFactor::class)
+            ->needs(RateLimiter::class)
+            ->give(function () use ($app) {
+                return new RateLimiter(cache()->store('memcached'))
+            });
+    })
+    ->create();
+```
+
 ## Validation
 
 Sometimes you may want to manually trigger a TOTP validation in any part of your application for the authenticated user. You can validate a TOTP code for the authenticated user using the `topt` rule.
@@ -421,7 +527,7 @@ public function checkTotp(Request $request)
 }
 ```
 
-This rule will succeed only if  the user is authenticated, it has Two-Factor Authentication enabled, and the code is correct or is a recovery code.
+This rule will succeed only if the user is authenticated, it has Two-Factor Authentication enabled, and the code is correct or is a recovery code.
 
 > [!TIP]
 >
@@ -495,6 +601,11 @@ return [
         'size' => 400,
         'margin' => 4
     ],
+    'throttle' => [
+        'enable' => env('OTP_THROTTLE'),
+        'amount' => [6, 60],
+        'route' => '2fa.confirm'
+    ]
 ];
 ```
 
@@ -639,6 +750,24 @@ return [
 
 This controls the size and margin used to create the QR Code, which are created as SVG.
 
+### Throttling
+
+```php
+return [
+    'throttle' => [
+        'enable' => env('OTP_THROTTLE', false),
+        'tries' => [6, 60],
+        'session_key' => '_totp_throttle',
+        'route' => '2fa.throttle'
+        'lifetime' => 10
+    ],
+];
+```
+
+This configures the [throttling global middleware](#throttling-middleware). The most important part is the route to redirect the user once the application throttles the user request, and where in the session to save this data.
+
+The `lifetime` key sets how many minutes to "bypass" the throttler after the user has been already throttled.
+
 ## Custom TOTP Label
 
 You may change how your model creates a TOTP Label, which is shown to the user on its authenticator, using the `getTwoFactorIssuer()` and `getTwoFactorUserIdentifier()` methods of your user.