Merge pull request #135 from dotkernel/issue121

Added security section with basic guidelines, fixed typos

Author: arhimede

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

@@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api`
 
 ### Issuing API Tokens
 
-Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows
+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:

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

@@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api`
 
 ### Issuing API Tokens
 
-Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows
+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:

docs/book/v5/openapi/write-documentation.md

@@ -107,4 +107,4 @@ To summarize, the typical scenario on working on your own instance of Dotkernel
 - create new module (example: `Book`)
 - add functionality to your new module (routes, entities, repositories, handlers, services, tests etc)
 - create file `OpenAPI.php` in the new module and describe each new endpoint
-- generate latest version of documentation file as described [here](./generate-documentation.md)
+- generate latest version of documentation file as described [in this tutorial](./generate-documentation.md)

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

@@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api`
 
 ### Issuing API Tokens
 
-Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows
+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:

docs/book/v6/extended-features/handler-structure.md

@@ -5,7 +5,7 @@ The goal of this update is to implement PSR-15 handlers into Dotkernel API.
 
 ## What is a handler?
 
-In DotKernel 6.0, a "handler" is the piece of code that reacts when a user makes a specific request (like visiting a webpage or submitting a form).
+In Dotkernel 6.0, a "handler" is the piece of code that reacts when a user makes a specific request (like visiting a webpage or submitting a form).
 It's basically the "controller" that decides what happens next.
 
 HTTP request handlers are at the core of any web application.
@@ -38,6 +38,6 @@ In this way, the developer can easily figure out the functionality of each handl
 
 ## Mapping of the handlers
 
-The full mapping of the handlers and their current paths and actions can be found [**here**](https://docs.dotkernel.org/img/api/v6/naming-convention.png).
+The full mapping of the handlers and their current paths and actions can be found in the full [naming convention table](https://docs.dotkernel.org/img/api/v6/naming-convention.png).
 
 [![naming-convention-thumbnail](https://docs.dotkernel.org/img/api/v6/naming-convention-thumbnail.png)](https://docs.dotkernel.org/img/api/v6/naming-convention.png)

docs/book/v6/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-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-15 applications by using the [thephpleague/oauth2-server](https://github.com/thephpleague/oauth2-server) package.
 
 ## Email
 

docs/book/v6/openapi/write-documentation.md

@@ -107,4 +107,4 @@ To summarize, the typical scenario on working on your own instance of Dotkernel
 - create new module (example: `Book`)
 - add functionality to your new module (routes, entities, repositories, handlers, services, tests etc)
 - create file `OpenAPI.php` in the new module and describe each new endpoint
-- generate latest version of documentation file as described [here](./generate-documentation.md)
+- generate latest version of documentation file as described [in this tutorial](./generate-documentation.md)

docs/book/v6/security/basic-security.md

@@ -0,0 +1,86 @@
+# Basic Security
+
+Dotkernel API provides all necessary tools to implement safe applications, however you will need to manually make use of some of them.
+This section will go over the provided tools and any steps you need to follow in order to use them successfully, as well as a few general considerations.
+
+## User Input Validation
+
+In order to validate user input, Dotkernel API makes use of [laminas/laminas-inputfilter](https://github.com/laminas/laminas-inputfilter).
+It is strongly recommended that custom functionality parsing user input also make use of input filters to validate the data.
+
+## Content Negotiation
+
+Content negotiation in Dotkernel API is done by a middleware configured using the `config/autoload/content-negotiation.global.php` file.
+
+Whenever an endpoint needs custom `Accept` and/or `Content-Type`, make sure that you set them in the above file.
+
+> Read more about [content negotiation](https://www.dotkernel.com/dotkernel-api/content-negotiation-in-dotkernel-rest-api/) and the way it is implemented in [Dotkernel API](../core-features/content-validation.md).
+
+## Cross-Origin Resource Sharing
+
+Dotkernel API uses [mezzio/mezzio-cors](https://github.com/mezzio/mezzio-cors) to handle CORS details.
+The default configuration, found in `config/autoload/cors.local.php`, makes the application accessible by any origin.
+
+Make sure your application specifies only the required origins when in a production environment.
+
+> This step is described in the [CORS](../tutorials/cors.md) tutorial.
+
+## Role-Based Access Control
+
+This project makes use of [mezzio/mezzio-authorization-rbac](../core-features/authorization.md) to handle access control.
+
+The default use cases have already been configured, but any custom functionality will require additional configuration to make sure it is protected.
+Update the configuration file of this package (`config/autoload/authorization.global.php`) whenever you add new routes or roles.
+
+## Demo Credentials
+
+Dotkernel API ships with two demo accounts: an admin account (`admin`) and a user account (`[email protected]`),
+with public identities and passwords as described in the [token authentication tutorial](https://docs.dotkernel.org/api-documentation/v6/tutorials/token-authentication/).
+
+Make sure to **update** or **remove** these demo accounts in your production environment.
+
+## Error Reporting Endpoint and ErrorReportingTokens
+
+The error reporting endpoint (`/error-report`) is intended to be used by third parties to report errors back to your application.
+This endpoint requires its own token type, namely an `ErrorReportingToken`, that is to be added in the configuration file for every application sending reports.
+
+Since these tokens do not have an expiration date, consider periodically refreshing them manually.
+
+This feature is configured using the `config/autoload/error-handling.global.php` file, under the configured `ErrorReportServiceInterface::class` key.
+
+This file is visible to your VCS by default, so take care not to overwrite tokens locally and commit them to your production environment.
+Additionally, make sure the `ip_whitelist` or `domain_whitelist` keys are set to your desired values, especially when in a production environment.
+
+> Read more about the [error reporting](../core-features/error-reporting.md) feature.
+
+## OpenAPI Documentation
+
+In order to provide an interactive documentation, Dotkernel API implemented [zircote/swagger-php](https://github.com/zircote/swagger-php).
+
+Make sure **not** to include sensitive data as examples for any of the documented endpoints.
+It is not recommended to enable the documentation in a production environment.
+
+> Read more about the [OpenAPI documentation](../openapi/introduction.md).
+
+## PHP Dependencies
+
+Dotkernel API uses `composer` to handle PHP dependencies.
+In time, make sure to review any common vulnerabilities and exposures for your dependencies.
+
+> You may also keep an eye on the Dotkernel API changelog for any updates relevant to your project.
+
+## General Considerations
+
+- `*.global.php` and `*.php.dist` configuration files are visible to the VCS, make sure **not** to include sensitive data in commits.
+    - `*.local.php` configuration files are ignored by the VCS by default and are the recommended place for sensitive data such as API keys.
+- Make sure the `development mode` is correctly set - **do not** enable `development mode` in a production environment.
+    - You can use the following command to check the current status:
+
+```shell
+composer development-status
+```
+
+- Dotkernel API ships with a [Laminas Continuous Integration](https://github.com/laminas/laminas-continuous-integration-action) GitHub Action,
+  if you are using a public repository consider keeping it in your custom applications to ensure code quality.
+
+> Read more about using [Laminas Continuous Integration](https://getlaminas.org/blog/2024-08-05-using-laminas-continuous-integration.html).

docs/book/v6/security/oauth2-security.md

@@ -0,0 +1,32 @@
+# OAuth2 Security
+
+Dotkernel API uses the [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) component to provide the OAuth2 authentication service.
+As a security stating point, when developing an application using this project make sure you go over the following steps.
+
+## Default OAuth Clients
+
+The project ships with the default OAuth clients `admin` and `frontend` with passwords equal to their names, as described in the [Authentication](https://docs.dotkernel.org/api-documentation/v6/core-features/authentication/) guide.
+
+These clients **must not** remain unchanged in your production environment, as they are a security risk -
+ensure you deleted them or updated the passwords.
+
+## OAuth Token Lifetime and Refresh Hygiene
+
+The configuration for OAuth2 tokens can be edited in `config/autoload/local.php` under the `authentication` key.
+
+By default, the lifetimes of the `access` and `refresh` tokens are set to one day and one month respectively.
+Make sure to adjust their values in accordance to your application's needs, with lower values being generally safer.
+
+> If your application requires it, you can revoke user OAuth tokens before their expiration by making use of the `revokeTokens` method of `UserService`.
+> Read more about the available [configuration options](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration).
+
+## Autogeneration of Cryptographic Keys
+
+Dotkernel API makes use of the `./vendor/bin/generate-oauth2-keys` command from `mezzio-authentication-oauth2` to automatically regenerate the
+public/private key pair used to verify the transmitted JWTs.
+This process is done after each `composer update` (or `composer install` with no lock file), as specified in `composer.json` under the `scripts.post-update-cmd` key.
+
+While hidden to the VCS by default, keep in mind not to commit any local keys.
+
+> Autogeneration of keys can be disabled by simply removing the `php ./vendor/bin/generate-oauth2-keys` command from the mentioned key.
+> While not related to Dotkernel API itself, do ensure that the directory containing the keys is properly secured.

mkdocs.yml

@@ -68,6 +68,9 @@ nav:
           - "Render Documentation": v6/openapi/render-documentation.md
           - "Use Documentation": v6/openapi/use-documentation.md
           - "Getting Help": v6/openapi/getting-help.md
+      - Basic Security:
+          - "Basic Security": v6/security/basic-security.md
+          - "OAuth2 Security": v6/security/oauth2-security.md
       - Reference:
           - "Anonymize Accounts": v6/reference/account-anonymization.md
   - v5: