Merge pull request #101 from Howriq/issue-96

issue #96: new structure: split the code in Core and App

Author: arhimede

docs/book/v5/introduction/introduction.md

@@ -29,7 +29,7 @@ Therefore, for every preflight request, there is at least one Router request.
 ## OAuth 2.0
 
 OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your Dotkernel API.
-We use [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using the [thephpleague/oauth2-server]https://github.com/thephpleague/oauth2-server package.
+We use [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) which provides OAuth 2.0 authentication for Mezzio and PSR-7 applications by using the [thephpleague/oauth2-server]https://github.com/thephpleague/oauth2-server package.
 
 ## Email
 

docs/book/v5/introduction/packages.md

@@ -20,13 +20,13 @@
 * `laminas/laminas-inputfilter` - Normalize and validate input sets from the web, APIs, the CLI, and more, including files
 * `laminas/laminas-stdlib` - SPL extensions, array utilities, error handlers, and more
 * `mezzio/mezzio` - PSR-15 Middleware Microframework
-* `mezzio/mezzio-authentication-oauth2` - OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications
+* `mezzio/mezzio-authentication-oauth2` - OAuth2 (server) authentication middleware for Mezzio and PSR-15 applications
 * `mezzio/mezzio-authorization-acl` - laminas-permissions-acl adapter for mezzio-authorization
 * `mezzio/mezzio-authorization-rbac` - mezzio authorization rbac adapter for laminas/laminas-permissions-rbac
 * `mezzio/mezzio-cors` - CORS component for Mezzio and other PSR-15 middleware runners
 * `mezzio/mezzio-fastroute` - FastRoute integration for Mezzio
-* `mezzio/mezzio-hal` - Hypertext Application Language implementation for PHP and PSR-7
-* `mezzio/mezzio-problem-details` - Problem Details for PSR-7 HTTP APIs addressing the RFC 7807 standard
+* `mezzio/mezzio-hal` - Hypertext Application Language implementation for PHP and PSR-15
+* `mezzio/mezzio-problem-details` - Problem Details for PSR-15 HTTP APIs addressing the RFC 7807 standard
 * `mezzio/mezzio-twigrenderer` - Twig integration for Mezzio
 * `ramsey/uuid-doctrine` - Use ramsey/uuid as a Doctrine field type
 * `roave/psr-container-doctrine` - Doctrine Factories for PSR-11 Containers

docs/book/v5/upgrading/UPGRADE-5.3.md

@@ -1,3 +1,4 @@
+
 # UPGRADE FROM 5.2 TO 5.3
 
 -------------------------

docs/book/v6/commands/create-admin-account.md

@@ -0,0 +1,40 @@
+# Creating admin accounts in Dotkernel API
+
+## Usage
+
+Run the following command in your application’s root directory:
+
+```shell
+php ./bin/cli.php admin:create-admin -i {IDENTITY} -p {PASSWORD} -f {FIRST_NAME} -l {LAST_NAME}
+```
+
+OR
+
+```shell
+php ./bin/cli.php admin:create-admin --identity {IDENTITY} --password {PASSWORD} --firstName {FIRST_NAME} --lastName {LAST_NAME}
+```
+
+after replacing:
+
+* {IDENTITY} with a valid username OR email address
+* {PASSWORD} with a valid password
+* {FIRST_NAME} and {LAST_NAME} with valid names
+
+**NOTE:**
+
+* if the specified fields contain special characters, make sure you surround them with double quote signs
+* this method does not allow specifying an admin role – newly created accounts will have role of admin
+
+If the submitted data is valid, the outputted response is:
+
+```text
+Admin account has been created.
+```
+
+The new admin account is ready to use.
+
+You can get more help with this command by running:
+
+```shell
+php ./bin/cli.php help admin:create
+```

docs/book/v6/commands/display-available-endpoints.md

@@ -0,0 +1,73 @@
+# Displaying Dotkernel API endpoints using dot-cli
+
+## Usage
+
+Run the following command in your application’s root directory:
+
+```shell
+php ./bin/cli.php route:list
+```
+
+The command runs through all routes and extracts endpoint information in realtime.
+The output should be similar to the following:
+
+```text
++-------------------- 37 Routes ------+-------------------------------------+
+| Request method | Route name                          | Route path                          |
++----------------+-------------------------------------+-------------------------------------+
+| GET            | app::view-index                     | /                                   |
+| GET            | admin::list-admin                   | /admin                              |
+| POST           | admin::create-admin                 | /admin                              |
+| GET            | admin::view-account                 | /admin/account                      |
+| PATCH          | admin::update-account               | /admin/account                      |
+| GET            | admin::list-role                    | /admin/role                         |
+| GET            | admin::view-role                    | /admin/role/{uuid}                  |
+| DELETE         | admin::delete-admin                 | /admin/{uuid}                       |
+| GET            | admin::view-admin                   | /admin/{uuid}                       |
+| PATCH          | admin::update-admin                 | /admin/{uuid}                       |
+| POST           | app::create-error-report            | /error-report                       |
+| POST           | security::token                     | /security/token                     |
+| GET            | user::list-user                     | /user                               |
+| POST           | user::create-user                   | /user                               |
+| DELETE         | user::delete-account                | /user/account                       |
+| GET            | user::view-account                  | /user/account                       |
+| PATCH          | user::update-account                | /user/account                       |
+| POST           | user::create-account                | /user/account                       |
+| POST           | user::request-activate-account      | /user/account/activate              |
+| PATCH          | user::activate-account              | /user/account/activate/{hash}       |
+| DELETE         | user::delete-account-avatar         | /user/account/avatar                |
+| GET            | user::view-account-avatar           | /user/account/avatar                |
+| POST           | user::create-account-avatar         | /user/account/avatar                |
+| POST           | user::recover-account               | /user/account/recover               |
+| POST           | user::create-account-reset-password | /user/account/reset-password        |
+| GET            | user::check-account-reset-password  | /user/account/reset-password/{hash} |
+| PATCH          | user::update-account-reset-password | /user/account/reset-password/{hash} |
+| GET            | user::list-role                     | /user/role                          |
+| GET            | user::view-role                     | /user/role/{uuid}                   |
+| DELETE         | user::delete-user                   | /user/{uuid}                        |
+| GET            | user::view-user                     | /user/{uuid}                        |
+| PATCH          | user::update-user                   | /user/{uuid}                        |
+| PATCH          | user::activate-user                 | /user/{uuid}/activate               |
+| DELETE         | user::delete-user-avatar            | /user/{uuid}/avatar                 |
+| GET            | user::view-user-avatar              | /user/{uuid}/avatar                 |
+| POST           | user::create-user-avatar            | /user/{uuid}/avatar                 |
+| PATCH          | user::deactivate-user               | /user/{uuid}/deactivate             |
++------+----------------+-------------------------------------+-------------------------------------+
+
+```
+
+## Filtering results
+
+The following filters can be applied when displaying the routes list:
+
+* Filter routes by name, using: `-i|--name[=NAME]`
+* Filter routes by path, using: `-p|--path[=PATH]`
+* Filter routes by method, using: `-m|--method[=METHOD]`
+
+The filters are case-insensitive and can be combined.
+
+Get more help by running this command:
+
+```shell
+php ./bin/cli.php route:list --help
+```

docs/book/v6/commands/generate-database-migrations.md

@@ -0,0 +1,64 @@
+# Generate a database migration without dropping custom tables
+
+## Usage
+
+Run the following command in your application’s root directory:
+
+```shell
+vendor/bin/doctrine-migrations diff
+```
+
+If you have mapping modifications, this will create a new migration file under `data/doctrine/migrations/` directory.
+Opening the migration file, you will notice that it contains some queries that will drop your `oauth_*` tables because they are unmapped (there is no doctrine entity describing them).
+You should delete your latest migration with the DROP queries in it as we will create another one, without the DROP queries in it.
+In order to avoid dropping these tables, you need to add a parameter called `filter-expression`.
+
+The command to be executed without dropping these tables looks like this:
+
+On Windows (use double quotes):
+
+```shell
+vendor/bin/doctrine-migrations diff --filter-expression="/^(?!oauth_)/"
+```
+
+On Linux/macOS (use single quotes):
+
+```shell
+vendor/bin/doctrine-migrations diff --filter-expression='/^(?!oauth_)/'
+```
+
+## Filtering multiple unmapped table patterns
+
+If your database contains multiple unmapped table groups, then the pattern in `filter-expression` should hold all table prefixes concatenated by pipe character (`|`).
+For example, if you need to filter tables prefixed with `foo_` and `bar_`,  then the command should look like this:
+
+On Windows:
+
+```shell
+vendor/bin/doctrine-migrations diff --filter-expression="/^(?!foo_|bar_)/"
+```
+
+On Linux/macOS:
+
+```shell
+vendor/bin/doctrine-migrations diff --filter-expression='/^(?!foo_|bar_)/'
+```
+
+## Troubleshooting
+
+On Windows, running the command in PowerShell might still add the `DROP TABLE oauth_*` queries to the migration file.
+This happens because for PowerShell the caret (`^`) is a special character, so it gets dropped (`"/^(?!oauth_)/"` becomes `"/(?!oauth_)/"` when it reaches your command).
+Escaping it will not help either.
+In this case, we recommend running the command:
+
+* directly from your IDE
+* using `Linux shell`
+* from the `Command Prompt`
+
+## Help
+
+You can get more help with this command by running:
+
+```shell
+vendor/bin/doctrine-migrations help diff
+```

docs/book/v6/commands/generate-tokens.md

@@ -0,0 +1,66 @@
+# Generating tokens in Dotkernel API
+
+This is a multipurpose command that allows creating tokens required by different parts of the API.
+
+## Usage
+
+Go to your application's root directory.
+
+Run the token generator command by executing the following command:
+
+```shell
+php ./bin/cli.php token:generate <type>
+```
+
+Where `<type>` is one of the following:
+
+* [error-reporting](#generate-error-reporting-token)
+
+If you need help using the command, execute the following command:
+
+```shell
+php ./bin/cli.php token:generate --help
+```
+
+### Generate error reporting token
+
+You can generate an error reporting token by executing the following command:
+
+```shell
+php ./bin/cli.php token:generate error-reporting
+```
+
+The output should look similar to this:
+
+```text
+Error reporting token:
+
+    0123456789abcdef0123456789abcdef01234567
+```
+
+Copy the generated token.
+
+Open `config/autoload/error-handling.global.php` and paste the copied token as shown below:
+
+```php
+return [
+    ...
+    ErrorReportServiceInterface::class => [
+        ...
+        'tokens' => [
+            '0123456789abcdef0123456789abcdef01234567',
+        ],
+        ...
+    ]
+]
+```
+
+Save and close `config/autoload/error-handling.global.php`.
+
+**Note**:
+
+If your application is NOT in development mode, make sure you clear your config cache by executing:
+
+```shell
+php ./bin/clear-config-cache.php
+```

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

@@ -0,0 +1,120 @@
+# Authentication
+
+Authentication is the process by which an identity is presented to the application. It ensures that the entity
+making the request has the proper credentials to access the API.
+
+**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`.
+
+## Configuration
+
+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.
+
+> You can check the
+> [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)
+> configuration part for more info.
+
+## How it works
+
+Dotkernels API authentication system can be used for SPAs (single-page applications), mobile applications, and
+simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts.
+
+The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
+
+## Database
+
+When you install **Dotkernel API** for the first time, you need to run the migrations and seeders. 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.
+
+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**).
+
+As you guessed each client serves to authenticate `admin` or `user`.
+
+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` `grand_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:
+
+- `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`
+
+```shell
+POST /security/generate-token HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+{
+  "grant_type": "password",
+  "client_id": "frontend",
+  "client_secret": "frontend",
+  "scope": "api",
+  "username": "[email protected]",
+  "password": "dotkernel"
+}
+```
+
+The server responds with a JSON as follows:
+
+```json
+{
+    "token_type": "Bearer",
+    "expires_in": 86400,
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+    "refresh_token": "def5020087199939a49d0f2f818..."
+}
+```
+
+Next time when you make a request to the server to an authenticated endpoint, the client should use
+the `Authorization` header request.
+
+```shell
+GET /users/1 HTTP/1.1
+Accept: application/json
+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
+
+```shell
+POST /security/refresh-token HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+{
+  "grant_type": "refresh_token",
+  "client_id": "frontend",
+  "client_secret": "frontend",
+  "scope": "api",
+  "refresh_token" : "def5020087199939a49d0f2f818..."
+}
+```
+
+The server responds with a JSON as follows:
+
+```json
+{
+  "token_type": "Bearer",
+  "expires_in": 86400,
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
+  "refresh_token": "def5020087199939a49d0f2f818..."
+}
+```