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..fff9b5b 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,15 @@ 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) +[![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) - ## Installation Run the following command in you project directory + ```bash $ composer require dotkernel/dot-authorization ``` @@ -29,14 +30,17 @@ 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; ``` + * 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..bb812f9 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# 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) | +| <= 2.x | :x: | | + +## 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..97b7fcb --- /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 diff --git a/docs/book/v3/overview.md b/docs/book/v3/overview.md new file mode 100644 index 0000000..7916f16 --- /dev/null +++ b/docs/book/v3/overview.md @@ -0,0 +1,3 @@ +# Overview + +`dot-authorization` is DotKernel's authorization base package which define interfaces for authorization services to be used with DotKernel applications. diff --git a/docs/book/v3/usage.md b/docs/book/v3/usage.md new file mode 100644 index 0000000..e4d18c9 --- /dev/null +++ b/docs/book/v3/usage.md @@ -0,0 +1,33 @@ +# 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 diff --git a/phpunit.xml b/phpunit.xml index 00092cd..7a99a94 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -7,4 +7,10 @@ ./test + + + + ./src + +