V7 overhaul

docs/book/v7/core-features/authentication.md

@@ -6,11 +6,18 @@ It ensures that the entity making the request has the proper credentials to acce
 **Dotkernel API** identities are delivered to the application from the client through the `Authorization` request.
 If it is present, the application tries to find and assign the identity to the application.
 If it is not presented, Dotkernel API assigns a default `guest` identity, represented by an instance of the class `Mezzio\Authentication\UserInterface`.
+Guests can access public endpoints but cannot access protected resources (those requiring user or admin roles).
+Check out the [Authorization page](https://docs.dotkernel.org/api-documentation/v7/core-features/authentication/) for more details on role-based access.
 
 ## Configuration
 
+Dotkernel API uses the **OAuth2 password grant flow** for authentication.
+This allows users to exchange their credentials (username/password) for access tokens.
+These tokens are then used for later requests instead of repeatedly sending credentials.
+
 Authentication in Dotkernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already configured out of the box.
-But if you want to dig more, the configuration is stored in `config/autoload/local.php` under the `authentication` key.
+To customize authentication behavior (token lifetimes, algorithms, etc.), edit `config/autoload/local.php` under the `authentication` key.
+See the [Mezzio OAuth2 documentation](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration) for all available options.
 
 > You can check the
 > [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)
@@ -23,32 +30,46 @@ It allows each user of your application to generate API tokens for their account
 
 The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
 
-## Database
+### Database
 
-When you install **Dotkernel API** for the first time, you need to run the migrations and seeders.
+When you install **Dotkernel API** for the first time, you need to run the migrations and seeders (fixtures).
 All the tables required for authentication are automatically created and populated.
 
-In Dotkernel API, authenticated users come from either the `admin` or the `user` table.
-We choose to keep the admin table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators of the application should access.
+```shell
+php ./vendor/bin/doctrine-migrations migrate
+php ./bin/doctrine fixtures:execute
+```
+
+The commands above create OAuth tables (oauth_clients, oauth_scopes, oauth_*) and seed the initial credentials:
+
+- **Admin**: identity=admin, password=dotadmin
+- **User**: identity=test@dotkernel.com, password=dotkernel
 
-The `oauth_clients` table is pre-populated with the default `admin` and `frontend` clients with the same password as their names (**we recommend you change the default passwords**).
+Check out the [Installation Guide](https://docs.dotkernel.org/api-documentation/v7/installation/doctrine-orm/) for more details.
 
-As you guessed each client serves to authenticate `admin` or `user`.
+In Dotkernel API, authenticated users come from either the `admin` or the `user` tables.
+We chose to keep the admin and user tables separate to prevent users of the application from accessing sensitive data that only administrators should access.
 
 Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
 
 ### Issuing API Tokens
 
 Token generation in Dotkernel API is done using the `password` `grant_type` scenario, which in this case allows authentication to an API using the user's credentials (generally a username and password).
 
-The client sends a POST request to the `/security/generate-token` with the following parameters:
+The `POST /security/generate-token` endpoint accepts OAuth2 credentials and returns both an access token (for making API calls) and a refresh token (for refreshing expired access tokens).
+
+The client requires the following parameters:
 
-- `grant_type` = password.
-- `client_id` = column `name` from the `oauth_clients` table
-- `client_secret` = column `secret` from the `oauth_clients` table
-- `scope` = column `scope` from the `oauth_scopes` table
-- `username` = column `identity` from table `admin`/`user`
-- `password` = column `password` from table `admin`/`user`
+| Field           | Type   | Purpose                                                  | Example                |
+|-----------------|--------|----------------------------------------------------------|------------------------|
+| `grant_type`    | string | OAuth2 flow type                                         | `"password"`           |
+| `client_id`     | string | OAuth client identifier from the `oauth_clients` table   | `"frontend"`           |
+| `client_secret` | string | OAuth client credential from the `oauth_clients` table   | `"frontend"`           |
+| `scope`         | string | Permission scope from the `oauth_scopes` table           | `"api"`                |
+| `username`      | string | User identity (email/username) from table `admin`/`user` | `"test@dotkernel.com"` |
+| `password`      | string | User password                                            | `"dotkernel"`          |
+
+This is what the call should look like:
 
 ```shell
 POST /security/generate-token HTTP/1.1
@@ -75,7 +96,14 @@ The server responds with a JSON as follows:
 }
 ```
 
-Next time when you make a request to the server to an authenticated endpoint, the client should use the `Authorization` header request.
+| Field           | Type    | Lifetime                             | Purpose                               |
+|-----------------|---------|--------------------------------------|---------------------------------------|
+| `token_type`    | string  | N/A                                  | Header value type                     |
+| `expires_in`    | integer | N/A                                  | Seconds until access token expires    |
+| `access_token`  | string  | 86400 seconds = 1 day (configurable) | Used in `Authorization` header        |
+| `refresh_token` | string  | 1 month (configurable)               | Used to refresh expired access tokens |
+
+On later requests to the server for an authenticated endpoint, the client should use the `Authorization` header request.
 
 ```shell
 GET /users/1 HTTP/1.1
@@ -85,24 +113,22 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
 
 ### Refreshing tokens
 
-Dotkernel API can refresh the access token, based on the expired access token's `refresh_token`.
-
-The clients need to send a `POST` request to the `/security/refresh-token` with the following request:
+When an access token expires, use the refresh token (received during token generation) to obtain a new access token without re-entering credentials:
 
 ```shell
-POST /security/refresh-token HTTP/1.1
+POST /security/refresh-token
 Accept: application/json
 Content-Type: application/json
 {
   "grant_type": "refresh_token",
   "client_id": "frontend",
   "client_secret": "frontend",
   "scope": "api",
-  "refresh_token" : "def5020087199939a49d0f2f818..."
+  "refresh_token": "def5020087199939a49d0f2f818..."
 }
 ```
 
-The server responds with a JSON as follows:
+The response contains a new `access_token` and `refresh_token`:
 
 ```json
 {
@@ -112,3 +138,50 @@ The server responds with a JSON as follows:
   "refresh_token": "def5020087199939a49d0f2f818..."
 }
 ```
+
+## Common Issues
+
+### "Invalid credentials" error
+
+- Check username/password are correct.
+- Verify client_id and client_secret match OAuth client in the database.
+- Confirm the user account exists and is active.
+
+### "Token has expired" error
+
+- Use refresh_token to get a new access_token.
+- If refresh_token is expired, re-authenticate with credentials.
+
+### "Invalid scope" error
+
+- Verify `scope` field is set to `"api"` (the only configured scope)
+
+## Flow Diagram
+
+```quote
+User Credentials
+      ↓
+POST /security/generate-token
+      ↓
+Access Token + Refresh Token
+      ↓
+Store tokens securely  ←─────────────────────────┐
+      ↓                                          |
+Include Access Token in Authorization header     |
+      ↓                                          |
+Make API requests                                |
+      ↓                                          |
+Token expires?                                   |
+      ↓ (yes)                                    |
+POST /security/refresh-token with refresh_token  |
+      ↓                                          |
+Get new Access Token  ───────────────────────────┘
+```
+
+## Security Best Practices
+
+- **Store tokens securely**: Never commit tokens to version control. Use environment variables or secure storage.
+- **Use HTTPS only**: OAuth2 tokens should only be transmitted over HTTPS in production.
+- **Rotate credentials**: Change default OAuth client secrets in production.
+- **Token expiration**: Access tokens expire (default 1 day). Implement refresh logic in clients.
+- **Never expose refresh tokens**: Refresh tokens should only be stored client-side, never in logs or public code.

docs/book/v7/installation/composer.md

@@ -1,32 +1,56 @@
 # Composer Installation of Packages
 
-Composer is required to install Dotkernel `api`. You can install Composer from the [official site](https://getcomposer.org/).
+In this step you will:
 
-> First, make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
+- [Install dependencies](#install-dependencies-using-composer).
+- [Enable development mode](#development-mode).
 
-## Install dependencies
+> Composer is required to install Dotkernel `api`.
+> You can install Composer from the [official site](https://getcomposer.org/).
+
+> Before you begin, make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
+
+## Install Dependencies Using Composer
 
 Run this command in the command prompt.
 
 > Use the **CLI** to ensure interactivity for proper configuration.
+> In some IDEs, Composer may not be able to prompt for configuration settings.
 
 ```shell
 composer install
 ```
 
+The automatic setup script performs these tasks:
+
+- Installs the packages listed in the `composer.json` file and their dependencies into the `vendor` folder.
+- Creates the `composer.lock` file that locks all dependencies to exact versions (you can still run `composer update` to replace them with newer versions, if available and installable without conflicts).
+- Configures PHP CodeSniffer, a utility to detect code style errors in PHP code.
+- Generate and save the OAuth2 keys in the `data/oauth` folder.
+    - Performed by this script `./bin/generate-oauth2-keys.php`.
+- Creates the initial `config/autoload` configuration files.
+    - Performed by this script `./bin/composer-post-install-script.php`.
+    - These files are created:
+        - config/autoload/local.php
+        - config/autoload/local.test.php
+        - config/autoload/mail.global.php
+
+> The post install commands are run automatically on every `composer install` and `composer update`.
+> The scripts check if the files exist to prevent overwriting them.
+
 You should see this text below, along with a long list of packages to be installed instead of the `[...]`.
-In this example there are 164 packages, though the number can change in future updates.
-You will find the packages in the `vendor` folder.
+
+> In this example there are 146 packages, though the number can change in future updates.
 
 ```shell
 No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.
 Loading composer repositories with package information
 Updating dependencies
-Lock file operations: 164 installs, 0 updates, 0 removals
+Lock file operations: 146 installs, 0 updates, 0 removals
 [...]
 Writing lock file
 Installing dependencies from lock file (including require-dev)
-Package operations: 164 installs, 0 updates, 0 removals
+Package operations: 146 installs, 0 updates, 0 removals
 [...]
 ```
 
@@ -42,8 +66,8 @@ Please select which config file you wish to inject 'Laminas\Diactoros\ConfigProv
 
 Type `0` to select `[0] Do not inject`.
 
-> We choose `0` because Dotkernel includes its own ConfigProvider, which already contains the prompted configurations.
-> If you choose `[1] config/config.php`, an extra `ConfigProvider` will be injected.
+> If you choose `1`, an extra `ConfigProvider` will be injected, which may return an error for packages you add in the future.
+> Choosing `0` prevents duplicate ConfigProvider registrations, as Dotkernel already includes its own.
 
 The next question is:
 
@@ -53,20 +77,29 @@ Type `y` here, and hit `enter` to complete this stage.
 
 ## Development mode
 
-If you're installing the project for development, make sure you have development mode enabled by running:
+Normally, a new project starts in development mode to prevent caching certain files in the `data/cache` folder.
+Enable development mode by running:
 
 ```shell
 composer development-enable
 ```
 
-You can disable the development mode by running:
+The confirmation message should read:
+
+```shell
+You are now in development mode.
+```
+
+If you ever need to disable the development mode, run:
 
 ```shell
 composer development-disable
 ```
 
-You can check if you have development mode enabled by running:
+This command displays the development mode status:
 
 ```shell
 composer development-status
 ```
+
+You should see the message `Development mode is ENABLED` or `Development mode is DISABLED`.

docs/book/v7/installation/configuration-files.md

@@ -1,20 +1,31 @@
 # Configuration Files
 
-> The installation script should have already created the files mentioned on this page.
-> We mention them explicitly because you will need to visit them to fully configure your development environment.
+The post-update scripts from `composer.json` (under the key `post-update-cmd`) should have already created the files mentioned on this page.
+
+> We mention these files explicitly because you will need to visit them to fully configure your development environment.
+> You will need to do the same for the production environment when you deploy your application.
 
 ## Prepare config files
 
-* duplicate `config/autoload/cors.local.php.dist` as `config/autoload/cors.local.php`
+The installation script will duplicate the following files:
+
+* `config/autoload/cors.local.php.dist` as `config/autoload/cors.local.php`.
 
 > If your API is consumed by another application, make sure to configure the `allowed_origins` variable.
+> Normally, the other configuration items in `cors.local.php` should be left as-is.
+> If you need to tweak them, visit the [CORS tutorial](https://docs.dotkernel.org/api-documentation/v7/tutorials/cors/).
+
+* `config/autoload/local.php.dist` as `config/autoload/local.php`.
 
-* duplicate `config/autoload/local.php.dist` as `config/autoload/local.php`
+> `local.php` is the main configuration file for your application.
+> It contains the database connection parameters, the API key, and other configuration items.
 
-* duplicate `config/autoload/mail.local.php.dist` as `config/autoload/mail.local.php`
+* `config/autoload/mail.local.php` from the `dot-mail` package installed in the `vendor` folder.
 
-> If your API sends emails, make sure to fill in SMTP connection params
+> If your API sends emails, you also need to configure the `mail` key.
+> Most often, you will be using either `Sendmail` or `SMTP` to send emails.
+> If you opt for `SMTP`, ake sure to configure the SMTP connection parameters under the `smtp_options` key.
 
-* **optional**: to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`
+* `config/autoload/local.test.php.dist` as `config/autoload/local.test.php` to run and create tests.
 
 > This creates a new in-memory database that your tests will run on.