diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml index 18c0fe4..edc0e50 100644 --- a/.github/workflows/continuous-integration.yml +++ b/.github/workflows/continuous-integration.yml @@ -14,9 +14,8 @@ jobs: strategy: matrix: php-version: - - "8.2" - - "8.3" - "8.4" + - "8.5" steps: - name: "Checkout" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..66f988d --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,31 @@ +# Releasing this package: Actions -> Release -> Run workflow, pick the branch +# (7.x) and type the version. Or from a terminal: +# +# gh workflow run release.yml --ref 7.x -f version=7.0.0 +# +# The shared workflow creates the tag itself, and only after every check has +# passed. Do not tag by hand -- Packagist derives versions from tags, so a tag +# is a published version the moment it exists. +# +# Release notes come from this package's own CHANGELOG.md. The version you type +# must match the version at the top of the change log -- or, for a pre-release +# such as 7.0.0-alpha1, its base version, so that alphas and betas do not each +# need a change log section of their own. + +name: Release + +on: + workflow_dispatch: + inputs: + version: + description: 'Version to release, e.g. 7.0.0' + required: true + type: string + +jobs: + release: + uses: auraphp/bin/.github/workflows/release.yml@v1.0.0 + permissions: + contents: write + with: + version: ${{ inputs.version }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e8597a..55384d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ # CHANGELOG -## 6.0.0 +## 7.0.0 -- PHP 8.2+ is now required. +- PHP 8.4+ is now required. - (ADD) Built-in OAuth 2.0 support. A new `Aura\Auth\Adapter\OAuth2Adapter` runs the authorization-code exchange and maps the resource owner to `[$username, $userdata]` via a configurable `username_field` or `map` callback. Providers are reached through a small `Aura\Auth\OAuth\ProviderInterface` seam (with a `LeagueProvider` wrapper for `league/oauth2-client`, kept as a `suggest`/`require-dev` dependency so the core stays dependency-light). A new `Aura\Auth\OAuth\AuthorizationCodeFlow` drives the flow securely: it generates and persists the anti-CSRF `state` and a PKCE `code_verifier` when supported, and `handleCallback()` handles provider errors, validates `state` in constant time (consuming it), and returns only the validated `code`/`code_verifier` to pass to `login()` — never raw `$_GET`. Build with `AuthFactory::newOAuth2Adapter()` and `AuthFactory::newOAuth2Flow()`. See `docs/oauth.md`. - (ADD) "Remember me" support (issue #4). A new `Aura\Auth\Remember\RememberService` issues, resumes, and forgets long-lived login tokens using the split-token (selector/validator) scheme with server-side storage and per-use token rotation. Storage is pluggable via `RememberStorageInterface`, with a PDO-backed `PdoRememberStorage` provided. A new `Status::REMEMBERED` (and `Auth::isRemembered()`) marks users re-authenticated from a cookie as lower privilege than credentialed (`VALID`) users. The `LoginService`, `LogoutService`, and `ResumeService` accept an optional `RememberService` so the feature works through existing call sites; the added constructor parameters are nullable and backward compatible. Build the pieces with `AuthFactory::newRememberService()` and `AuthFactory::newPdoRememberStorage()`. See the README "Remember Me" section. - (ADD) LDAP "bind, search, rebind" support (issue #45). `Aura\Auth\Adapter\LdapAdapter` accepts an optional `search` configuration (`binddn`, `bindpw`, `basedn`, `filter`, and optional `attributes`); when given, it binds with a service account, searches for the user's real DN — which may live anywhere in the tree, so users spread across multiple OUs are now supported — then rebinds as that DN to verify the password, returning the discovered attributes. Without `search` it behaves exactly as before (direct bind via `dnformat`), so the change is backward compatible. A failed search operation raises the new `Aura\Auth\Exception\SearchFailed`, kept distinct from a successful zero-result search (`UsernameNotFound`). Configure via `AuthFactory::newLdapAdapter()`. A real-OpenLDAP integration test suite (opt-in via `LDAP_TEST_URI`) runs in CI. See `docs/adapters.md`. @@ -16,13 +16,13 @@ - (FIX) `NativeRedisClient` no longer reports a failed Redis read as a failure count of zero. `hashGetAll()` folded any non-array reply into an empty array, which `RedisThrottleStorage::getFailures()` reads as "no failures recorded" — so a key that could not be read silently switched throttling off for that account, and stayed off, because the matching `hincrby`/`hset` writes were dropped just as quietly. Commands whose failure is reported by return value rather than by exception now raise `Exception\ConnectionFailed`, which fails closed: `ThrottleService::assert()` runs before the wrapped adapter, so a broken backend blocks attempts instead of waving them through, matching `PdoThrottleStorage`, which already lets PDO's exceptions propagate. This is narrower than it sounds — phpredis throws of its own accord when the connection is refused or drops, so an unreachable Redis already failed closed; what is covered is chiefly `WRONGTYPE`, when another application shares the database and puts a non-hash under the throttle prefix. The guard tests for an exact `false`: `HSET` and `DEL` answer `0` on ordinary outcomes and `EXPIRE` answers `false` for a key that no longer exists, so a looser check would throw on healthy traffic; `expire()` and `delete()` stay unchecked for that reason, and a dropped `delete()` errs safe anyway by leaving the counter in place. - (FIX) `HtpasswdVerifier`'s APR1/MD5 computation is now reachable as `computeApr1()`, split out of `apr1()` so a dummy in that format can be generated. PHP's `crypt()` has no `$apr1$` support — it answers `*0` — so the package's own implementation is the only source of a valid one; a `*0` would have fallen through `verify()` to the DES branch and cost the wrong amount while still looking plausible. Verification behaviour is unchanged, and is now checked against real `htpasswd -m` output. - (FIX) Compare hashes with `hash_equals()` rather than `===` in `PasswordVerifier` (the `hash()` algorithm path) and in `HtpasswdVerifier`'s SHA, APR1/MD5, and DES paths, so comparison time no longer depends on how many leading characters matched. The original code predates `hash_equals()`, which arrived in PHP 5.6 — after this code was written against a `php >=5.4.0` requirement. -- (ADD) Depend on the new `aura/session-interface` (`^6.0`) package, which provides the shared session/segment contracts. +- (ADD) Depend on the new `aura/session-interface` (`^7.0`) package, which provides the shared session/segment contracts. - (CHG) `AuthFactory`, `Auth`, and the `LoginService`/`LogoutService`/`ResumeService` now type-hint the shared `Aura\Session_Interface\SessionInterface` and `SegmentInterface`. As a result an `Aura\Session\Session` and its segments — or any other implementation of the shared contracts — can now be passed to Aura.Auth directly, while the built-in light `Session`/`Segment` continue to work standalone. - (CHG) `Aura\Auth\Session\SessionInterface` and `Aura\Auth\Session\SegmentInterface` are deprecated. They now simply extend the shared interfaces and are retained only for backward compatibility; type-hint the `Aura\Session_Interface` versions instead. - (CHG) Add native `string`/`mixed`/`bool`/`void` type declarations to `Session`, `Segment`, `NullSession`, and `NullSegment` to match the shared interfaces. - (CHG) Use explicit nullable types (`?Type`) for parameters that default to `null` in `AuthFactory` and `ImapAdapter`, fixing the PHP 8.4 implicit-nullable deprecation. - (TST) Update test doubles and test classes for PHP 8.2 (declared properties instead of dynamic ones). -- (TST) Require `phpunit/phpunit` `^11.0` and modernize the suite for it: mock proxied `Phpfunc` functions via real test doubles with `onlyMethods()` (replacing the removed `addMethods()`), use `willReturn()` instead of `will($this->returnValue())`, and migrate doc-comment metadata (`@runInSeparateProcess`, `@runTestsInSeparateProcesses`, `@preserveGlobalState`) to PHP attributes. The CI matrix now targets PHP 8.2/8.3/8.4. +- (TST) Require `phpunit/phpunit` `^11.0` and modernize the suite for it: mock proxied `Phpfunc` functions via real test doubles with `onlyMethods()` (replacing the removed `addMethods()`), use `willReturn()` instead of `will($this->returnValue())`, and migrate doc-comment metadata (`@runInSeparateProcess`, `@runTestsInSeparateProcesses`, `@preserveGlobalState`) to PHP attributes. The CI matrix now targets PHP 8.4/8.5. - (CHG) Remove Psalm: drop the `vimeo/psalm` dev dependency, the `psalm.xml` config, and the Psalm CI job. - (CHG) Document that passing a `hash()` algorithm name to `PasswordVerifier` (`new PasswordVerifier('md5')`) compares an unsalted digest with no work factor, and exists only so a site with a legacy password column can authenticate users while migrating them. `docs/adapters.md` gained the warning and a migration recipe, and a stale reference to `HashVerifier` was corrected — that class was merged into `PasswordVerifier` in 2014. A new `docs/security.md` collects the account-enumeration and password-storage notes, including the part the application owns: adapters throw distinct `UsernameNotFound` and `PasswordIncorrect` exceptions for logging, and rendering them as different messages hands an attacker what the timing fix protects. - (ADD) A `docs/schemas.md` reference with `CREATE TABLE` statements for SQLite, MySQL/MariaDB, and PostgreSQL covering the `aura_auth_remember`, `aura_auth_token`, and `aura_auth_throttle` tables, plus an example `accounts` table. The page publishes the same `.sql` files the new PDO integration job executes, so the documented schema is one that is tested rather than one written from memory; a test fails if the two drift apart. Previously the only per-engine guidance was a parenthetical in a class docblock. diff --git a/README.md b/README.md index bb4c833..7328c46 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Note that the purpose of this package is only to authenticate user credentials. ### Installation -This library requires PHP 8.2 or later, and depends only on [aura/session-interface](https://packagist.org/packages/aura/session-interface) for its shared session contracts. +This library requires PHP 8.4 or later, and depends only on [aura/session-interface](https://packagist.org/packages/aura/session-interface) for its shared session contracts. It is installable and autoloadable via Composer as [aura/auth](https://packagist.org/packages/aura/auth). @@ -24,8 +24,8 @@ Alternatively, [download a release](https://github.com/auraphp/Aura.Auth/release ### Quality -[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/auraphp/Aura.Auth/badges/quality-score.png?b=6.x)](https://scrutinizer-ci.com/g/auraphp/Aura.Auth/) -[![Continuous Integration](https://github.com/auraphp/Aura.Auth/actions/workflows/continuous-integration.yml/badge.svg?branch=6.x)](https://github.com/auraphp/Aura.Auth/actions/workflows/continuous-integration.yml) +[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/auraphp/Aura.Auth/badges/quality-score.png?b=7.x)](https://scrutinizer-ci.com/g/auraphp/Aura.Auth/) +[![Continuous Integration](https://github.com/auraphp/Aura.Auth/actions/workflows/continuous-integration.yml/badge.svg?branch=7.x)](https://github.com/auraphp/Aura.Auth/actions/workflows/continuous-integration.yml) To run the unit tests at the command line, issue `composer install` and then `vendor/bin/phpunit` at the package root. This requires [Composer](http://getcomposer.org/) to be available as `composer`. diff --git a/composer.json b/composer.json index 497b014..b2ceb2c 100644 --- a/composer.json +++ b/composer.json @@ -16,25 +16,22 @@ } ], "require": { - "php": "^8.2", - "aura/session-interface": "^6.0" + "php": "^8.4", + "aura/session-interface": "^7.0@beta" }, "autoload": { "psr-4": { "Aura\\Auth\\": "src/" } }, - "minimum-stability": "dev", - "prefer-stable": true, "require-dev": { - "aura/session": "7.x-dev", + "aura/session": "7.x-dev@dev", "phpunit/phpunit": "^11.0", "league/oauth2-client": "^2.7" }, "autoload-dev": { "psr-4": { - "Aura\\Auth\\": "tests/", - "Aura\\Di\\": "vendor/aura/di/tests/" + "Aura\\Auth\\": "tests/" } }, "suggest": { diff --git a/docs/_bookdown.json b/docs/_bookdown.json index e887d34..6a689cf 100644 --- a/docs/_bookdown.json +++ b/docs/_bookdown.json @@ -1,5 +1,5 @@ { - "title": "Aura.Auth 6.x", + "title": "Aura.Auth 7.x", "content": [ "getting-started.md", "adapters.md", diff --git a/docs/index.md b/docs/index.md index eb3184e..76acdf8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,4 +11,4 @@ - [Database Schemas](schemas.md) - [Session Management](sessions.md) - [DI Configuration](di-configuration.md) -- [Upgrade Guide: 4.x → 6.0.0](upgrade.md) +- [Upgrade Guide: 4.x → 7.0.0](upgrade.md) diff --git a/docs/sessions.md b/docs/sessions.md index 7e39ee9..fa471bc 100644 --- a/docs/sessions.md +++ b/docs/sessions.md @@ -5,7 +5,7 @@ The _Service_ objects use a _Session_ object to start sessions and regenerate se ## Using Aura.Session You don't have to write a custom wrapper to use a full-featured session library. -Since 6.0.0, `AuthFactory` (and everything it builds — `Auth`, the +Since 7.0.0, `AuthFactory` (and everything it builds — `Auth`, the `LoginService` / `LogoutService` / `ResumeService`, and the OAuth `AuthorizationCodeFlow`) type-hints the shared `Aura\Session_Interface` contracts. [Aura.Session](https://github.com/auraphp/Aura.Session)'s own diff --git a/docs/upgrade.md b/docs/upgrade.md index 16807c1..fb773fd 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -1,16 +1,16 @@ -# Upgrade Guide: 4.x → 6.0.0 +# Upgrade Guide: 4.x → 7.0.0 -This guide summarizes the changes in 6.0.0 that affect existing code. For the -full list, see the [CHANGELOG](https://github.com/auraphp/Aura.Auth/blob/6.x/CHANGELOG.md). +This guide summarizes the changes in 7.0.0 that affect existing code. For the +full list, see the [CHANGELOG](https://github.com/auraphp/Aura.Auth/blob/7.x/CHANGELOG.md). ## PHP Version Requirement -PHP 8.2 or later is now required. +PHP 8.4 or later is now required. ## New Dependency: `aura/session-interface` Aura.Auth now depends on the [`aura/session-interface`](https://packagist.org/packages/aura/session-interface) -(`^6.0`) package, which provides the shared session and segment contracts. This +(`^7.0`) package, which provides the shared session and segment contracts. This is installed automatically via Composer. ## Shared Session Contracts @@ -39,7 +39,7 @@ signatures accordingly. ## New Feature: Remember Me -6.0.0 adds "remember me" support (issue #4): +7.0.0 adds "remember me" support (issue #4): - A new `Status::REMEMBERED` constant and `Auth::isRemembered()` method mark users re-authenticated from a cookie as **lower privilege** than credentialed @@ -60,5 +60,5 @@ chapter for full setup. ## Tooling The test suite now requires `phpunit/phpunit` `^11.0`, and the CI matrix targets -PHP 8.2 / 8.3 / 8.4. The `vimeo/psalm` dev dependency has been removed. These +PHP 8.4 / 8.5. The `vimeo/psalm` dev dependency has been removed. These changes affect contributors only, not consumers of the library.