From ca7c80b50e293230017f00aea1587e02dfd58387 Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Thu, 11 Apr 2024 12:13:06 +0300 Subject: [PATCH 1/4] Documentation v2 dot-authentication --- .github/workflows/continuous-integration.yml | 11 +++++ .github/workflows/cs-tests.yml | 47 ------------------- .github/workflows/docs-build.yml | 16 +++++++ .github/workflows/static-analysis.yml | 47 ------------------- .github/workflows/unit-tests.yaml | 48 -------------------- SECURITY.md | 38 ++++++++++++++++ docs/book/index.md | 1 + docs/book/v2/configuration.md | 3 ++ docs/book/v2/installation.md | 5 ++ docs/book/v2/overview.md | 3 ++ docs/book/v2/usage.md | 40 ++++++++++++++++ mkdocs.yml | 19 ++++++++ 12 files changed, 136 insertions(+), 142 deletions(-) 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 delete mode 100644 .github/workflows/unit-tests.yaml create mode 100644 SECURITY.md create mode 100644 docs/book/index.md create mode 100644 docs/book/v2/configuration.md create mode 100644 docs/book/v2/installation.md create mode 100644 docs/book/v2/overview.md create mode 100644 docs/book/v2/usage.md create mode 100644 mkdocs.yml 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 e8bbade..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 install --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 6f7452d..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 install --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/.github/workflows/unit-tests.yaml b/.github/workflows/unit-tests.yaml deleted file mode 100644 index 7f5f333..0000000 --- a/.github/workflows/unit-tests.yaml +++ /dev/null @@ -1,48 +0,0 @@ -on: - - push - -name: Run PHPUnit tests - -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 install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run PHPUnit tests - run: vendor/bin/phpunit --colors=always diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..aa1e46b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,38 @@ +# Security Policy + +## Supported Versions + + +| Version | Supported | PHP Version | +|---------|--------------------|--------------------------------------------------------------------------------------------------------------------| +| 2.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-authentication/2.3.4) | + + +## 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/v2/configuration.md b/docs/book/v2/configuration.md new file mode 100644 index 0000000..1b49a0c --- /dev/null +++ b/docs/book/v2/configuration.md @@ -0,0 +1,3 @@ +# Configuration + +Please note that usually this package will be installed as a dependency to a concrete implementation, so usually you won't need to add this to you project manually. diff --git a/docs/book/v2/installation.md b/docs/book/v2/installation.md new file mode 100644 index 0000000..46463d0 --- /dev/null +++ b/docs/book/v2/installation.md @@ -0,0 +1,5 @@ +# Installation + +Install `dot-authentication` by executing the following Composer command: + + composer require dotkernel/dot-authentication diff --git a/docs/book/v2/overview.md b/docs/book/v2/overview.md new file mode 100644 index 0000000..e0d7f51 --- /dev/null +++ b/docs/book/v2/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. diff --git a/docs/book/v2/usage.md b/docs/book/v2/usage.md new file mode 100644 index 0000000..7f63eb9 --- /dev/null +++ b/docs/book/v2/usage.md @@ -0,0 +1,40 @@ +# Usage + +## AuthenticationInterface + +Defines the interface that should be implemented by any authentication service, in order to work with DotKernel applications. This is a result of the fact that the default packages used by DotKernel applications, that need access to the authentication service are type-hinted against this interface. + +Also, concrete implementations should be registered in the service manager using this interface's FQN. + +### Methods + +```php +public function authenticate(ServerRequestInterface $request): AuthenticationResult; +``` +* method to implement the actual authentication process. It should extract credentials from the `$request` object(Authorization header, custom request attributes etc.). It should return an `AuthenticationResult` object, defined in this package, which carry the authentication status and identity on success. + +```php +public function challenge(ServerRequestInterface $request): ResponseInterface; +``` +* this method should return a valid PSR-7 `ResponseInterface` used to notify the client or browser that it needs to authenticate first(usually using the `WWW-Authenticate` header - usefull for HTTP basic and digest authentication) + +```php +public function hasIdentity(): bool; +public function getIdentity(): ?IdentityInterface; +public function setIdentity(IdentityInterface $identity); +public function clearIdentity(); +``` + +* these methods are used to check if authenticated, get the authenticated identity object, force set an identity(maybe useful for auto-login) or clear an identity(logout) + +## IdentityInterface + +You can use any object to represent an authenticated identity(user) as long as it implements this interface. It requires 2 methods, `getId()` which should return the unique identifier of the identity, and `getName(): string` which should return a string representation of the identity(for display purposes, usually the email or username) + +## AuthenticationResult + +Returned by the authentication service, on authentication success or failure. It composes one of the predefined authentication codes, which describes the authentication status, an error message in case the authentication has failed, and the identity object on success. + +## UnauthorizedException + +Exception to be thrown when accessing content that need authentication first. This can be used within an application to trigger an error and do a custom action(like redirecting to a login page). There is not a predefined way to handle this, DotKernel packages use this exception paired with a custom error handler to handle unauthorized errors. When using the frontend or admin applications, this is already setup among the authentication/authorization packages, and throwing an UnauthorizedException from anywhere your application, it will redirect to the login page by default. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..800c1d8 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,19 @@ +docs_dir: docs/book +site_dir: docs/html +extra: + project: Packages + current_version: v2 + versions: + - v2 +nav: + - Home: index.md + - v2: + - Overview: v2/overview.md + - Installation: v2/installation.md + - Configuration: v2/configuration.md + - Usage: v2/usage.md +site_name: dot-authentication +site_description: "Core interfaces for authentication implementations" +repo_url: "https://github.com/dotkernel/dot-authentication" +plugins: + - search From b816bd4ba9fe20a53221eaa4b0c198422e5e44ad Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 09:33:08 +0300 Subject: [PATCH 2/4] fixed readme.md and usage.md errors --- README.md | 6 ++++-- docs/book/v2/usage.md | 2 ++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eba2100..81d36ae 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,14 @@ Authentication base package defining interfaces for authentication services to b [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-authentication)](https://github.com/dotkernel/dot-authentication/stargazers) [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-authentication)](https://github.com/dotkernel/dot-authentication/blob/2.0/LICENSE.md) -[![Build Static](https://github.com/dotkernel/dot-authentication/actions/workflows/static-analysis.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/dot-authentication/actions/workflows/static-analysis.yml) +[![Build Static](https://github.com/dotkernel/dot-authentication/actions/workflows/continuous-integration.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/dot-authentication/actions/workflows/continuous-integration.yml) [![SymfonyInsight](https://insight.symfony.com/projects/8a0dfa12-fdda-43d7-bdbe-1c6996b30c12/big.svg)](https://insight.symfony.com/projects/8a0dfa12-fdda-43d7-bdbe-1c6996b30c12) ## Installation Run the following command in you project directory + ```bash $ composer require dotkernel/dot-authentication ``` @@ -34,11 +35,13 @@ Also, concrete implementations should be registered in the service manager using ```php public function authenticate(ServerRequestInterface $request): AuthenticationResult; ``` + * method to implement the actual authentication process. It should extract credentials from the `$request` object(Authorization header, custom request attributes etc.). It should return an `AuthenticationResult` object, defined in this package, which carry the authentication status and identity on success. ```php public function challenge(ServerRequestInterface $request): ResponseInterface; ``` + * this method should return a valid PSR-7 `ResponseInterface` used to notify the client or browser that it needs to authenticate first(usually using the `WWW-Authenticate` header - usefull for HTTP basic and digest authentication) ```php @@ -50,7 +53,6 @@ public function clearIdentity(); * these methods are used to check if authenticated, get the authenticated identity object, force set an identity(maybe useful for auto-login) or clear an identity(logout) - ## IdentityInterface You can use any object to represent an authenticated identity(user) as long as it implements this interface. It requires 2 methods, `getId()` which should return the unique identifier of the identity, and `getName(): string` which should return a string representation of the identity(for display purposes, usually the email or username) diff --git a/docs/book/v2/usage.md b/docs/book/v2/usage.md index 7f63eb9..44bd6c2 100644 --- a/docs/book/v2/usage.md +++ b/docs/book/v2/usage.md @@ -11,11 +11,13 @@ Also, concrete implementations should be registered in the service manager using ```php public function authenticate(ServerRequestInterface $request): AuthenticationResult; ``` + * method to implement the actual authentication process. It should extract credentials from the `$request` object(Authorization header, custom request attributes etc.). It should return an `AuthenticationResult` object, defined in this package, which carry the authentication status and identity on success. ```php public function challenge(ServerRequestInterface $request): ResponseInterface; ``` + * this method should return a valid PSR-7 `ResponseInterface` used to notify the client or browser that it needs to authenticate first(usually using the `WWW-Authenticate` header - usefull for HTTP basic and digest authentication) ```php From cef352af1da7cd1f90e83be220ce63a5036cf1b1 Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 11:18:15 +0300 Subject: [PATCH 3/4] added old version to SECURITY.md and more tests --- README.md | 1 + SECURITY.md | 2 +- test/AuthenticationInterfaceTest.php | 44 +++++++++++++++++++ test/AuthenticationResultTest.php | 6 ++- .../InvalidArgumentExceptionTest.php | 28 ++++++++++++ test/Exception/RuntimeExceptionTest.php | 28 ++++++++++++ test/Exception/UnauthorizedExceptionTest.php | 28 ++++++++++++ test/Identity/IdentityInterfaceTest.php | 36 +++++++++++++++ 8 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 test/AuthenticationInterfaceTest.php create mode 100644 test/Exception/InvalidArgumentExceptionTest.php create mode 100644 test/Exception/RuntimeExceptionTest.php create mode 100644 test/Exception/UnauthorizedExceptionTest.php create mode 100644 test/Identity/IdentityInterfaceTest.php diff --git a/README.md b/README.md index 81d36ae..df8ea30 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Authentication base package defining interfaces for authentication services to b [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-authentication)](https://github.com/dotkernel/dot-authentication/blob/2.0/LICENSE.md) [![Build Static](https://github.com/dotkernel/dot-authentication/actions/workflows/continuous-integration.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/dot-authentication/actions/workflows/continuous-integration.yml) +[![codecov](https://codecov.io/gh/dotkernel/dot-authentication/graph/badge.svg?token=ZBZDEA3LY8)](https://codecov.io/gh/dotkernel/dot-authentication) [![SymfonyInsight](https://insight.symfony.com/projects/8a0dfa12-fdda-43d7-bdbe-1c6996b30c12/big.svg)](https://insight.symfony.com/projects/8a0dfa12-fdda-43d7-bdbe-1c6996b30c12) diff --git a/SECURITY.md b/SECURITY.md index aa1e46b..835d0e6 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,7 @@ | Version | Supported | PHP Version | |---------|--------------------|--------------------------------------------------------------------------------------------------------------------| | 2.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-authentication/2.3.4) | - +| <= 1.x | :x: | | ## Reporting Potential Security Issues diff --git a/test/AuthenticationInterfaceTest.php b/test/AuthenticationInterfaceTest.php new file mode 100644 index 0000000..a4a8ba3 --- /dev/null +++ b/test/AuthenticationInterfaceTest.php @@ -0,0 +1,44 @@ +mockAuthenticationInterface = $this->createMock(AuthenticationInterface::class); + $this->identityInterfaceMock = $this->createMock(IdentityInterface::class); + $this->identityInterfaceMock->method('getId')->will($this->returnValue(10)); + $this->identityInterfaceMock->method('getName')->willReturn('username'); + $this->mockAuthenticationInterface->method('hasIdentity')->willReturn(true); + $this->mockAuthenticationInterface->method('getIdentity')->willReturn($this->identityInterfaceMock); + } + + public function testCreate(): void + { + $this->assertInstanceOf(AuthenticationInterface::class, $this->mockAuthenticationInterface); + $this->assertInstanceOf(IdentityInterface::class, $this->identityInterfaceMock); + } + + public function testFunction(): void + { + $this->assertTrue($this->mockAuthenticationInterface->hasIdentity()); + $this->assertSame('username', $this->mockAuthenticationInterface->getIdentity()->getName()); + $this->assertSame(10, $this->mockAuthenticationInterface->getIdentity()->getId()); + } +} diff --git a/test/AuthenticationResultTest.php b/test/AuthenticationResultTest.php index 0f84c13..1cea2ab 100644 --- a/test/AuthenticationResultTest.php +++ b/test/AuthenticationResultTest.php @@ -26,6 +26,11 @@ protected function setUp(): void $this->subject = new AuthenticationResult(2, 'valid', $this->identityInterfaceMock); } + public function testCreate() + { + $this->assertInstanceOf(IdentityInterface::class, $this->identityInterfaceMock); + } + public function testAuth() { $code = $this->subject->getCode(); @@ -34,7 +39,6 @@ public function testAuth() $interface = $this->subject->hasIdentity(); $isValid = $this->subject->isValid(); - $this->assertInstanceOf(IdentityInterface::class, $name); $this->assertSame(2, $code); $this->assertSame('valid', $message); $this->assertSame('username', $name->getName()); diff --git a/test/Exception/InvalidArgumentExceptionTest.php b/test/Exception/InvalidArgumentExceptionTest.php new file mode 100644 index 0000000..c113633 --- /dev/null +++ b/test/Exception/InvalidArgumentExceptionTest.php @@ -0,0 +1,28 @@ +exceptionInterfaceMock = $this->createMock(InvalidArgumentException::class); + } + + public function testCreate(): void + { + $this->assertInstanceOf(InvalidArgumentException::class, $this->exceptionInterfaceMock); + } +} diff --git a/test/Exception/RuntimeExceptionTest.php b/test/Exception/RuntimeExceptionTest.php new file mode 100644 index 0000000..d6cc50f --- /dev/null +++ b/test/Exception/RuntimeExceptionTest.php @@ -0,0 +1,28 @@ +exceptionInterfaceMock = $this->createMock(RuntimeException::class); + } + + public function testCreate(): void + { + $this->assertInstanceOf(RuntimeException::class, $this->exceptionInterfaceMock); + } +} diff --git a/test/Exception/UnauthorizedExceptionTest.php b/test/Exception/UnauthorizedExceptionTest.php new file mode 100644 index 0000000..005ef60 --- /dev/null +++ b/test/Exception/UnauthorizedExceptionTest.php @@ -0,0 +1,28 @@ +exceptionInterfaceMock = $this->createMock(UnauthorizedException::class); + } + + public function testCreate(): void + { + $this->assertInstanceOf(UnauthorizedException::class, $this->exceptionInterfaceMock); + } +} diff --git a/test/Identity/IdentityInterfaceTest.php b/test/Identity/IdentityInterfaceTest.php new file mode 100644 index 0000000..146b4cf --- /dev/null +++ b/test/Identity/IdentityInterfaceTest.php @@ -0,0 +1,36 @@ +identityInterfaceMock = $this->createMock(IdentityInterface::class); + $this->identityInterfaceMock->method('getId')->will($this->returnValue(10)); + $this->identityInterfaceMock->method('getName')->willReturn('username'); + } + + public function testCreate(): void + { + $this->assertInstanceOf(IdentityInterface::class, $this->identityInterfaceMock); + } + + public function testFunction(): void + { + $this->assertSame('username', $this->identityInterfaceMock->getName()); + $this->assertSame(10, $this->identityInterfaceMock->getId()); + } +} From f3c8ba4d5e51c385c72a2733ca447e223b79fe64 Mon Sep 17 00:00:00 2001 From: poprazvan17 Date: Fri, 12 Apr 2024 11:27:17 +0300 Subject: [PATCH 4/4] added void to test function --- test/AuthenticationResultTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/AuthenticationResultTest.php b/test/AuthenticationResultTest.php index 1cea2ab..0c1cfeb 100644 --- a/test/AuthenticationResultTest.php +++ b/test/AuthenticationResultTest.php @@ -26,12 +26,12 @@ protected function setUp(): void $this->subject = new AuthenticationResult(2, 'valid', $this->identityInterfaceMock); } - public function testCreate() + public function testCreate(): void { $this->assertInstanceOf(IdentityInterface::class, $this->identityInterfaceMock); } - public function testAuth() + public function testAuth(): void { $code = $this->subject->getCode(); $message = $this->subject->getMessage();