From deb4ac886deb2252683136208512fd390ad30829 Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Thu, 11 Apr 2024 12:48:55 +0300 Subject: [PATCH 1/5] Documentation v3 dot-authorization --- .../{unit-tests.yaml => codecov.yml} | 18 ++++--- .github/workflows/continuous-integration.yml | 11 +++++ .github/workflows/cs-tests.yml | 47 ------------------- .github/workflows/docs-build.yml | 16 +++++++ .github/workflows/static-analysis.yml | 47 ------------------- README.md | 5 +- SECURITY.md | 38 +++++++++++++++ docs/book/index.md | 1 + docs/book/v3/configuration.md | 3 ++ docs/book/v3/instalation.md | 5 ++ docs/book/v3/overview.md | 3 ++ docs/book/v3/usage.md | 32 +++++++++++++ mkdocs.yml | 19 ++++++++ 13 files changed, 144 insertions(+), 101 deletions(-) rename .github/workflows/{unit-tests.yaml => codecov.yml} (67%) create mode 100644 .github/workflows/continuous-integration.yml delete mode 100644 .github/workflows/cs-tests.yml create mode 100644 .github/workflows/docs-build.yml delete mode 100644 .github/workflows/static-analysis.yml create mode 100644 SECURITY.md create mode 100644 docs/book/index.md create mode 100644 docs/book/v3/configuration.md create mode 100644 docs/book/v3/instalation.md create mode 100644 docs/book/v3/overview.md create mode 100644 docs/book/v3/usage.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/unit-tests.yaml b/.github/workflows/codecov.yml similarity index 67% rename from .github/workflows/unit-tests.yaml rename to .github/workflows/codecov.yml index 7f5f333..190b4da 100644 --- a/.github/workflows/unit-tests.yaml +++ b/.github/workflows/codecov.yml @@ -1,11 +1,11 @@ on: - push -name: Run PHPUnit tests +name: Run Codecov checks jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} + code-coverage: + name: Code Coverage runs-on: ${{ matrix.os }} @@ -27,8 +27,9 @@ jobs: uses: shivammathur/setup-php@v2 with: php-version: "${{ matrix.php }}" + coverage: pcov + ini-values: assert.exception=1, zend.assertions=1, error_reporting=-1, log_errors_max_len=0, display_errors=On tools: composer:v2, cs2pr - coverage: none - name: Determine composer cache directory run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV @@ -44,5 +45,10 @@ jobs: - name: Install dependencies with composer run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - name: Run PHPUnit tests - run: vendor/bin/phpunit --colors=always + - name: Collect code coverage with PHPUnit + run: vendor/bin/phpunit --colors=always --coverage-clover clover.xml + + - name: Send code coverage report to Codecov.io + uses: codecov/codecov-action@v3 + with: + token: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml new file mode 100644 index 0000000..26c5802 --- /dev/null +++ b/.github/workflows/continuous-integration.yml @@ -0,0 +1,11 @@ +name: "Continuous Integration" + +on: + pull_request: + push: + branches: + tags: + +jobs: + ci: + uses: laminas/workflow-continuous-integration/.github/workflows/continuous-integration.yml@1.x diff --git a/.github/workflows/cs-tests.yml b/.github/workflows/cs-tests.yml deleted file mode 100644 index e73dfcf..0000000 --- a/.github/workflows/cs-tests.yml +++ /dev/null @@ -1,47 +0,0 @@ -on: - - push - -name: Run phpcs checks - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - name: Install dependencies with composer - run: composer update --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run phpcs checks - run: vendor/bin/phpcs diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 0000000..1a7aa24 --- /dev/null +++ b/.github/workflows/docs-build.yml @@ -0,0 +1,16 @@ +name: docs-build + +on: + release: + types: [published] + workflow_dispatch: + +jobs: + build-deploy: + runs-on: ubuntu-latest + steps: + - name: Build Docs + uses: dotkernel/documentation-theme/github-actions/docs@main + env: + DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml deleted file mode 100644 index e9de91d..0000000 --- a/.github/workflows/static-analysis.yml +++ /dev/null @@ -1,47 +0,0 @@ -on: - - push - -name: Run static analysis - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - name: Install dependencies with composer - run: composer update --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run static analysis - run: vendor/bin/psalm --no-cache --output-format=github --show-info=false --threads=4 diff --git a/README.md b/README.md index f52ba1f..56836ed 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Authorization base package defining interfaces for authorization services to be [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-authorization)](https://github.com/dotkernel/dot-authorization/stargazers) [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-authorization)](https://github.com/dotkernel/dot-authorization/blob/3.0/LICENSE.md) -[![Build Static](https://github.com/dotkernel/dot-authorization/actions/workflows/static-analysis.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-authorization/actions/workflows/static-analysis.yml) +[![Build Static](https://github.com/dotkernel/dot-authorization/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-authorization/actions/workflows/continuous-integration.yml) [![SymfonyInsight](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364/big.svg)](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364) @@ -18,6 +18,7 @@ Authorization base package defining interfaces for authorization services to be ## Installation Run the following command in you project directory + ```bash $ composer require dotkernel/dot-authorization ``` @@ -32,11 +33,13 @@ Defines the interface that should be implemented by any authorization service, i ```php public function isGranted(string $permission, array $roles = [], $context = null): bool; ``` + * this is the only method that deals with authorization. Given a permission and a list of roles, should return a boolean value of true if at least one role has access to the requested permission. As you can see, we expect that the authorization service to be implemented as an RBAC. ## RoleInterface Defines the interface that Role objects must implement. A role object should be able to retrieve its name, so this interface has only one method defined + ```php public function getName(): string; ``` diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a3dde61 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,38 @@ +# Security Policy + +## Supported Versions + + +| Version | Supported | PHP Version | +|---------|--------------------|-------------------------------------------------------------------------------------------------------------------| +| 3.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-authorization/3.4.1) | + +## Reporting Potential Security Issues + +If you have encountered a potential security vulnerability in this project, +please report it to us at . We will work with you to +verify the vulnerability and patch it. + +When reporting issues, please provide the following information: + +- Component(s) affected +- A description indicating how to reproduce the issue +- A summary of the security vulnerability and impact + +We request that you contact us via the email address above and give the +project contributors a chance to resolve the vulnerability and issue a new +release prior to any public exposure; this helps protect the project's +users, and provides them with a chance to upgrade and/or update in order to +protect their applications. + + +## Policy + +If we verify a reported security vulnerability, our policy is: + +- We will patch the current release branch, as well as the immediate prior minor + release branch. + +- After patching the release branches, we will immediately issue new security + fix releases for each patched release branch. + diff --git a/docs/book/index.md b/docs/book/index.md new file mode 100644 index 0000000..fe84005 --- /dev/null +++ b/docs/book/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/book/v3/configuration.md b/docs/book/v3/configuration.md new file mode 100644 index 0000000..70109b0 --- /dev/null +++ b/docs/book/v3/configuration.md @@ -0,0 +1,3 @@ +# Configuration + +Please note that usually this pacakge will be installed as a dependency to a concrete implementation, so you won't need to add this to your project manually. diff --git a/docs/book/v3/instalation.md b/docs/book/v3/instalation.md new file mode 100644 index 0000000..8b63199 --- /dev/null +++ b/docs/book/v3/instalation.md @@ -0,0 +1,5 @@ +# Installation + +Install `dot-authorization` by executing the following Composer command: + + composer require dotkernel/dot-authorization \ No newline at end of file diff --git a/docs/book/v3/overview.md b/docs/book/v3/overview.md new file mode 100644 index 0000000..45126b0 --- /dev/null +++ b/docs/book/v3/overview.md @@ -0,0 +1,3 @@ +# Overview + +`dot-authentication` is DotKernel's authentication base package which define interfaces for authentication services to be used with DotKernel applications. \ No newline at end of file diff --git a/docs/book/v3/usage.md b/docs/book/v3/usage.md new file mode 100644 index 0000000..9a28cd8 --- /dev/null +++ b/docs/book/v3/usage.md @@ -0,0 +1,32 @@ +# Usage + +## AuthorizationInterface + +Defines the interface that should be implemented by any authorization service, in order to work with DotKernel applications. This is a result of the fact that, by default, any DotKernel package which has to do with authorization is assuming that a service is registered in the service container using as service name this interface's FQN + +### Methods +```php +public function isGranted(string $permission, array $roles = [], $context = null): bool; +``` + +* this is the only method that deals with authorization. Given a permission and a list of roles, should return a boolean value of true if at least one role has access to the requested permission. As you can see, we expect that the authorization service to be implemented as an RBAC. + +## RoleInterface + +Defines the interface that Role objects must implement. A role object should be able to retrieve its name, so this interface has only one method defined + +```php +public function getName(): string; +``` + +## IdentityInterface + +Interface that needs to be implemented by entities that support roles. They should be able to retrieve their roles by defining a `getRoles()` method. +The roles should be an array of role names or role objects + +This package is suitable for RBAC style authorization. Roles can be flat or hierarchical and they are assigned permissions. +A role is granted if it has the required permission. + +## ForbiddenException + +Exception to be thrown when accessing content without having the required permissions. This can be used withing an application to trigger a forbidden error and do a custom action(like displaying a forbidden page or redirecting). This package does not define how you should handle such situations. There is a concrete authorization implementation in [dot-rbac](https://github.com/dotkernel/dot-rbac) and a forbidden exception handler in [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) as DotKernel default packages for authorization. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..933f757 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,19 @@ +docs_dir: docs/book +site_dir: docs/html +extra: + project: Packages + current_version: v3 + versions: + - v3 +nav: + - Home: index.md + - v2: + - Overview: v3/overview.md + - Installation: v3/installation.md + - Configuration: v3/configuration.md + - Usage: v3/usage.md +site_name: dot-authorization +site_description: "DotKernel authorization service abstractions" +repo_url: "https://github.com/dotkernel/dot-authorization" +plugins: + - search From 54f1c71fe74f9cefcd08017d9826c9d393e5203f Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 09:39:01 +0300 Subject: [PATCH 2/5] fixed errors md files --- README.md | 2 +- docs/book/v3/instalation.md | 2 +- docs/book/v3/overview.md | 2 +- docs/book/v3/usage.md | 1 + 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 56836ed..1ecd788 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,6 @@ Authorization base package defining interfaces for authorization services to be [![SymfonyInsight](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364/big.svg)](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364) - ## Installation Run the following command in you project directory @@ -30,6 +29,7 @@ Please note that usually this pacakge will be installed as a dependency to a con Defines the interface that should be implemented by any authorization service, in order to work with DotKernel applications. This is a result of the fact that, by default, any DotKernel package which has to do with authorization is assuming that a service is registered in the service container using as service name this interface's FQN ### Methods + ```php public function isGranted(string $permission, array $roles = [], $context = null): bool; ``` diff --git a/docs/book/v3/instalation.md b/docs/book/v3/instalation.md index 8b63199..97b7fcb 100644 --- a/docs/book/v3/instalation.md +++ b/docs/book/v3/instalation.md @@ -2,4 +2,4 @@ Install `dot-authorization` by executing the following Composer command: - composer require dotkernel/dot-authorization \ No newline at end of file + composer require dotkernel/dot-authorization diff --git a/docs/book/v3/overview.md b/docs/book/v3/overview.md index 45126b0..e0d7f51 100644 --- a/docs/book/v3/overview.md +++ b/docs/book/v3/overview.md @@ -1,3 +1,3 @@ # Overview -`dot-authentication` is DotKernel's authentication base package which define interfaces for authentication services to be used with DotKernel applications. \ No newline at end of file +`dot-authentication` is DotKernel's authentication base package which define interfaces for authentication services to be used with DotKernel applications. diff --git a/docs/book/v3/usage.md b/docs/book/v3/usage.md index 9a28cd8..e4d18c9 100644 --- a/docs/book/v3/usage.md +++ b/docs/book/v3/usage.md @@ -5,6 +5,7 @@ Defines the interface that should be implemented by any authorization service, in order to work with DotKernel applications. This is a result of the fact that, by default, any DotKernel package which has to do with authorization is assuming that a service is registered in the service container using as service name this interface's FQN ### Methods + ```php public function isGranted(string $permission, array $roles = [], $context = null): bool; ``` From b76b35393e3029e31beeec1f421e7f5c617cf44b Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 10:25:07 +0300 Subject: [PATCH 3/5] added old version to Security.md table --- README.md | 1 + SECURITY.md | 1 + docs/book/v3/overview.md | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1ecd788..fff9b5b 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Authorization base package defining interfaces for authorization services to be [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-authorization)](https://github.com/dotkernel/dot-authorization/blob/3.0/LICENSE.md) [![Build Static](https://github.com/dotkernel/dot-authorization/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-authorization/actions/workflows/continuous-integration.yml) +[![codecov](https://codecov.io/gh/dotkernel/dot-authorization/graph/badge.svg?token=ZBZDEA3LY8)](https://codecov.io/gh/dotkernel/dot-authorization) [![SymfonyInsight](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364/big.svg)](https://insight.symfony.com/projects/014df510-1cf7-4876-b1a8-303fbef2f364) diff --git a/SECURITY.md b/SECURITY.md index a3dde61..bb812f9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,6 +6,7 @@ | Version | Supported | PHP Version | |---------|--------------------|-------------------------------------------------------------------------------------------------------------------| | 3.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-authorization/3.4.1) | +| <= 2.x | :x: | | ## Reporting Potential Security Issues diff --git a/docs/book/v3/overview.md b/docs/book/v3/overview.md index e0d7f51..da6d818 100644 --- a/docs/book/v3/overview.md +++ b/docs/book/v3/overview.md @@ -1,3 +1,3 @@ # Overview -`dot-authentication` is DotKernel's authentication base package which define interfaces for authentication services to be used with DotKernel applications. +`dot-authentication` is DotKernel's authorization base package which define interfaces for authentication services to be used with DotKernel applications. From 398afeb51c5e1bbd954afd9ad72fd25d378e4e11 Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 12:32:32 +0300 Subject: [PATCH 4/5] overview.md changed --- docs/book/v3/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/v3/overview.md b/docs/book/v3/overview.md index da6d818..7916f16 100644 --- a/docs/book/v3/overview.md +++ b/docs/book/v3/overview.md @@ -1,3 +1,3 @@ # Overview -`dot-authentication` is DotKernel's authorization base package which define interfaces for authentication services to be used with DotKernel applications. +`dot-authorization` is DotKernel's authorization base package which define interfaces for authorization services to be used with DotKernel applications. From bfc73790d3633ab1be4a7df1dc277ff9246d6512 Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 12:55:10 +0300 Subject: [PATCH 5/5] added codecov in phpunit --- phpunit.xml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/phpunit.xml b/phpunit.xml index 00092cd..7a99a94 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -7,4 +7,10 @@ ./test + + + + ./src + +