added totp pages - security, install tutorial

docs/book/v7/security/2fa-with-totp.md

@@ -0,0 +1,33 @@
+# Time-based One-Time Password (TOTP)
+
+A **Time-based One-Time Password (TOTP)** is a security algorithm used as part of **two-factor authentication (2FA)** to protect against account attacks.
+
+The mechanism is integrated into [dot-totp](https://github.com/dotkernel/dot-totp) to enhance security by requiring both a **password** and **an additional one-time code**.
+Our implementation follows the industry standard of using an Authenticator app to generate temporary, unique 6-digit codes that change every 30 seconds.
+
+## 2FA with TOTP Flow
+
+Below is a simplified flow for the 2FA with a TOTP mechanism.
+
+```mermaid
+sequenceDiagram
+    participant U as 👤 User
+    participant A as 📱 Authenticator App
+    participant S as 🖥 Server
+
+    U->>S: 1. Enter username + password
+    S->>S: 2. Verify credentials
+
+    S-->>U: 3. Request TOTP code
+
+    A->>U: 4. Display TOTP (time-based)
+    U->>S: 5. Submit TOTP code
+
+    S->>S: 6. Validate (shared secret + time)
+
+    S-->>U: 7. ✅ Access granted
+```
+
+## Next Steps
+
+[Install 2FA with dot-totp](../configuring-2fa-with-totp.md).

docs/book/v7/tutorials/install-dot-totp.md

@@ -0,0 +1,81 @@
+# Installing dot-totp into Dotkernel Admin
+
+If you haven't already, install [Dotkernel Admin](https://github.com/dotkernel/admin).
+
+> The installation steps listed below should work similarly in any middleware-based application.
+
+The first step is to include the package in your project by running this command:
+
+```shell
+composer require dotkernel/dot-totp
+```
+
+We will follow the Dotkernel file structure and create the files in the list below.
+If you follow the links from the [main totp integration example](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp), you can download the files and add them to your codebase.
+
+- [src/Admin/src/Form/RecoveryForm.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Form/RecoveryForm.php)
+- [src/Admin/src/Form/TotpForm.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Form/TotpForm.php)
+- [src/Admin/src/Handler/Account/GetDisableTotpFormHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetDisableTotpFormHandler.php)
+- [src/Admin/src/Handler/Account/GetEnableTotpFormHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetEnableTotpFormHandler.php)
+- [src/Admin/src/Handler/Account/GetRecoveryFormHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetRecoveryFormHandler.php)
+- [src/Admin/src/Handler/Account/GetTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetTotpHandler.php)
+- [src/Admin/src/Handler/Account/PostDisableTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostDisableTotpHandler.php)
+- [src/Admin/src/Handler/Account/PostEnableTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostEnableTotpHandler.php)
+- [src/Admin/src/Handler/Account/PostValidateRecoveryHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostValidateRecoveryHandler.php)
+- [src/Admin/src/Handler/Account/PostValidateTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostValidateTotpHandler.php)
+- [src/Admin/templates/admin/recovery-form.html.twig](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/templates/admin/recovery-form.html.twig)
+- [src/App/src/Middleware/CancelUrlMiddleware.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/App/src/Middleware/CancelUrlMiddleware.php)
+- [src/App/src/Middleware/TotpMiddleware.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/App/src/Middleware/TotpMiddleware.php)
+
+You can use the trait at [src/Core/src/App/src/Entity/TotpTrait.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Core/src/App/src/Entity/TotpTrait.php) in any entity where you need 2FA.
+
+> Make sure to migrate the new columns `totpSecret`, `totp_enabled` and `recovery_codes` in your entity.
+
+There are still some code snippets in the [_misc](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp) folder:
+
+- [the enable/disable 2FA button](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-view-account.html.twig) should be used in the `view-account.html.twig` file or in a new page.
+- [the routes updates](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-routes.php) must be added in the `src/Admin/src/RoutesDelegator.php` file.
+- [the pipeline updates](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-Pipeline.php) must be added in the `config/pipeline.php` file after `$app->pipe(AuthMiddleware::class);`.
+- [the ConfigProvider updates](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-ConfigProvider.php) must be added in the `src/Admin/src/ConfigProvider.php` file.
+
+## Dot-totp in Action
+
+Once you have `dot-totp` implemented, you can activate the feature in your admin accounts.
+If you navigate to your profile from the top-right image in Dotkernel Admin, you should see this box.
+
+![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/profile-totp-deactivated.jpg)
+
+Simply click on 'Enable TOTP' to begin the activation process.
+
+> We blurred out the QR code and recovery codes for this tutorial.
+> You will receive dynamically generated versions that will be fully visible to you.
+
+> You will need to have an Authenticator app installed on your mobile device.
+
+![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/totp-activate-qr.jpg)
+
+Follow the instructions on the screen:
+
+- Scan the QR code with your mobile device.
+- Enter the 6-digit code it generates on your mobile device.
+
+> The code refreshes every 30 seconds.
+
+The TOPT activation flow will list several recovery codes you can use if your mobile device isn't available.
+
+![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/totp-recovery-codes.jpg)
+
+> Each recovery code is usable only once.
+
+> Save the recovery codes in a secure location.
+
+If the code is valid, you will be logged in, and TOTP will be activated for your account.
+
+Whenever you need to log into the account, you will start by entering your username and password, like before.
+Since TOTP is activated, you will need to also submit the code from your Authenticator app.
+Alternatively, you can submit a recovery code.
+
+![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/totp-ask-code.jpg)
+
+That's it!
+You are now logged in securely.

mkdocs.yml

@@ -35,8 +35,10 @@ nav:
       - "Set Up CSRF": v7/how-to/csrf.md
     - Security:
         - "Basic Security": v7/security/basic-security.md
+        - "Two Factor Authorization with Time-based One-Time Password": v7/security/2fa-with-totp.md
     - Tutorials:
         - "Creating a book module using DotMaker": v7/tutorials/create-book-module-via-dot-maker.md
+        - "Installing dot-totp": v7/tutorials/install-dot-totp.md
   - v6:
     - Introduction: v6/introduction/introduction.md
     - Overview: