Release 0.2.0

.github/workflows/ci.yml

@@ -0,0 +1,176 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version: ["8.2", "8.3", "8.4", "8.5"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          coverage: none
+
+      - name: Validate Composer metadata
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Run tests
+        run: vendor/bin/phpunit test
+
+  oauth-real-providers:
+    # Validate integration using the actual optional League provider classes
+    # without sending requests to Google/Facebook or requiring live secrets.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          coverage: none
+
+      - name: Install test dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Install optional OAuth provider libraries for integration tests
+        run: |
+          composer require --dev --no-interaction --prefer-dist --no-progress \
+            'league/oauth2-google:^4.0' \
+            'league/oauth2-facebook:^2.0' \
+            'guzzlehttp/guzzle:^7.0'
+
+      - name: Assert real OAuth providers are available
+        run: |
+          php -r 'require "vendor/autoload.php"; exit(
+            class_exists("League\\OAuth2\\Client\\Provider\\Google") &&
+            class_exists("League\\OAuth2\\Client\\Provider\\Facebook") ? 0 : 1
+          );'
+
+      - name: Run real-provider OAuth integration tests
+        run: vendor/bin/phpunit test/RealOAuthProviderTest.php
+
+  migrations-mysql:
+    name: MySQL ${{ matrix.mysql-version }} migrations and DBAuth
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        mysql-version: ["8.0", "8.4"]
+
+    services:
+      mysql:
+        image: mysql:${{ matrix.mysql-version }}
+        env:
+          MYSQL_ROOT_PASSWORD: root_password
+          MYSQL_DATABASE: auth_test
+          MYSQL_USER: auth_user
+          MYSQL_PASSWORD: auth_password
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping --host=127.0.0.1 --user=auth_user --password=auth_password --silent"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+
+    env:
+      MYSQL_HOST: 127.0.0.1
+      MYSQL_PORT: 3306
+      MYSQL_DATABASE: auth_test
+      MYSQL_USER: auth_user
+      MYSQL_PASSWORD: auth_password
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          extensions: pdo_mysql
+          coverage: none
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Run bundled Phinx migrations on MySQL
+        run: vendor/bin/phinx migrate --configuration test/phinx.php --environment mysql_testing
+
+      - name: Verify MySQL migration status
+        run: vendor/bin/phinx status --configuration test/phinx.php --environment mysql_testing
+
+      - name: Verify MySQL schema, indexes and foreign keys
+        run: php test/verify_mysql_migrations.php
+
+      - name: Verify MySQL DBAuth authentication workflows
+        run: php test/verify_mysql_auth.php
+
+  migrations-postgresql:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: auth_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      PGHOST: 127.0.0.1
+      PGPORT: 5432
+      PGDATABASE: auth_test
+      PGUSER: postgres
+      PGPASSWORD: postgres
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.5"
+          extensions: pdo_pgsql
+          coverage: none
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Run bundled Phinx migrations
+        run: vendor/bin/phinx migrate --configuration test/phinx.php --environment testing
+
+      - name: Verify migration status
+        run: vendor/bin/phinx status --configuration test/phinx.php --environment testing
+
+      - name: Verify migrated schema
+        run: php test/verify_migrations.php
+
+      - name: Verify portable role lookup
+        run: php test/verify_postgresql_role_lookup.php

.github/workflows/release.yml

@@ -0,0 +1,109 @@
+name: Release verification
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  test:
+    # The regular CI workflow already tests the full PHP matrix on PRs.
+    # This release workflow runs the matrix after merge or when dispatched.
+    if: github.event_name != 'pull_request'
+    name: PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - '8.2'
+          - '8.3'
+          - '8.4'
+          - '8.5'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate Composer metadata
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer update --prefer-dist --no-interaction --no-progress
+
+      - name: Run tests
+        run: vendor/bin/phpunit test
+
+  production-install:
+    name: Production install
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate Composer metadata
+        run: composer validate --strict
+
+      - name: Verify production dependencies
+        run: |
+          composer install --no-dev --prefer-dist --no-interaction --no-progress --optimize-autoloader
+          composer check-platform-reqs --no-dev
+
+      - name: Smoke-test production autoload and authentication
+        run: php test/verify_production_install.php vendor/autoload.php
+
+      - name: Install as a separate production consumer
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/auth-consumer"
+          # This prerelease is not yet published on Packagist. Use a copied
+          # Composer path package (not a symlink) pinned to the candidate
+          # version, as a real consumer would install it into vendor/.
+          php -r '
+            $manifest = [
+              "name" => "objectiveweb/auth-production-consumer",
+              "description" => "Isolated no-dev install verification",
+              "require" => [
+                "php" => ">=8.2",
+                "objectiveweb/auth" => "^0.2",
+              ],
+              "repositories" => [[
+                "type" => "path",
+                "url" => getenv("GITHUB_WORKSPACE"),
+                "options" => [
+                  "symlink" => false,
+                  "versions" => ["objectiveweb/auth" => "0.2.0"],
+                ],
+              ]],
+            ];
+            file_put_contents(
+              getenv("RUNNER_TEMP") . "/auth-consumer/composer.json",
+              json_encode($manifest, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n"
+            );
+          '
+          cd "$RUNNER_TEMP/auth-consumer"
+          composer install --no-dev --prefer-dist --no-interaction --no-progress --optimize-autoloader
+          composer check-platform-reqs --no-dev
+          test -f vendor/objectiveweb/auth/src/Auth.php
+          php "$GITHUB_WORKSPACE/test/verify_production_install.php" "$PWD/vendor/autoload.php"
+

CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to `objectiveweb/auth` are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) conventions and [Semantic Versioning](https://semver.org/); releases prior to 1.0 may include breaking changes in minor versions.
+
+## [0.2.0] — Unreleased
+
+**Breaking release.** This is a rewrite of the 0.1.x public API and storage model, not a drop-in upgrade. Read the [0.2.0 upgrade guide](docs/UPGRADING-0.2.0.md) before updating an existing application.
+
+### Added
+
+- Abstract `Objectiveweb\Auth` provider contract, `Objectiveweb\Auth\DBAuth` backed by `objectiveweb/db ^0.8`, and an in-memory `BasicAuth` provider.
+- Separate user and `(provider, uid)` credential records, provider-specific profiles, UUIDs, configurable login/recovery providers, credential lifecycle (create, rename, delete) and per-credential verification status.
+- Bundled Phinx migrations for `user`, `user_credentials`, `role`, `user_roles`, and `delegations`, including credential verification/expiry columns.
+- Role-based authorization, `RequireRole` middleware, relational permissions/delegations, configurable eager loading, and `user_context_callback` for refreshing application-owned context in sessions.
+- `Controller\AuthController`, `Controller\OAuthController`, and admin-only `Controller\UserController` with paginated, filterable `Collection` results, credential management, invitations, password resets, lifecycle management and CSRF-protected writes.
+- Optional OAuth client login with Google/Facebook provider support, PKCE S256, provider/session-bound single-use state, and explicit, CSRF-protected account linking.
+- A **first-time OAuth account-choice flow**: an unknown provider identity remains pending for up to ten minutes. The user explicitly chooses to create a new account or sign into an existing password account to link; the provider callback creates no account by itself. Includes an example frontend.
+- Configurable callbacks for registration, token delivery, invitation/reset, audit events, deletion guards and application context.
+- PHP 8.2–8.5 tests, SQLite unit tests, PostgreSQL 16 migration/integration checks, MySQL 8.0/8.4 schema and authentication integration checks, real Google/Facebook provider-class tests with mocked HTTP, and pre-merge production/consumer Composer installation tests.
+
+### Changed
+
+- **Minimum PHP version raised from 5.3 to 8.2.** Runtime dependency: `objectiveweb/db ^0.8.0`. Router/Phinx/PHPUnit packages are development dependencies; applications using router middleware or OAuth providers must install the relevant integration packages themselves.
+- Database access moved from direct PDO/MySQL-specific SQL in `Objectiveweb\Auth` to the portable `DBAuth` abstraction. Queries now return `Objectiveweb\DB\Collection`, rather than the 0.1.x HAL-style `_embedded`/pagination array.
+- Local identifiers are represented as credentials (`provider = local`, `uid`); the user table no longer contains the legacy `username` identity column by default.
+- Password login failures return the same `AuthException` HTTP 401 for unknown identifiers, bad passwords and suspended accounts.
+- Password reset tokens are cryptographically random, stored only as SHA-256 digests, expire and are consumed atomically; previously issued plaintext legacy tokens do **not** carry forward.
+- Session IDs regenerate upon authentication; `user_can()` revalidates account status and roles on every call so deleted/suspended accounts and revoked roles cannot retain access through stale sessions. Public user payloads are sanitized.
+- User-facing password changes require the existing password, a session-bound `X-CSRF-Token`, and a JSON request; public registration is restricted to local credentials and safe profile fields.
+- OAuth callbacks require a **configured, trusted `redirectUri`** (HTTPS, or explicitly configured HTTP loopback for local development), no longer inferred from Host/proxy request headers.
+- OAuth provider-resource-owner display names, emails and avatars are optional hints with safe fallbacks; matching email addresses do **not** link accounts.
+- `BasicAuth::update_credential()` now preserves an existing provider profile when given `null`, matching `DBAuth` and preventing password login from erasing metadata.
+- User-managed application associations (`managed_relations`) now belong to application services. Use `user_context_callback` to expose current assignments to the authenticated session. User deletion cleans only explicitly `auth_owned` authorization relation tables; application-owned relation tables are never implicitly modified.
+- Project testing/release verification moved from Travis to GitHub Actions; Composer metadata and support URL updated.
+
+### Security fixes
+
+- Prevent account enumeration through password-login errors and anonymous password-recovery responses.
+- Allow anonymous password recovery only through independently verified credential channels (including local), preventing reset delivery to unverified emails/phone numbers; preserve generic responses and trusted administrator invitation/reset workflows.
+- Consume password reset and credential-verification tokens at most once; separate proof for each provider credential.
+- Revoke outstanding password-reset tokens and expirations whenever a user password is changed, atomically with the password hash update on DBAuth.
+- Prevent OAuth login CSRF, state replay, cross-provider state confusion, unconsented linking, email-based account takeover and cross-account credential reassignment.
+- Restrict logout redirects to safe same-origin absolute paths and reject attacker-controlled OAuth callback URLs.
+- Enforce management CSRF checks; check and serialize administrator removal, demotion and suspension inside DBAuth's existing update/delete transactions so concurrent operations cannot remove the final active admin (including direct DBAuth calls and lifecycle-field updates). Routine profile writes skip the lock; controllers retain self-protection and validation. Reject unknown DELETE subresources with 404 instead of accidentally deleting the user.
+- Avoid returning passwords, reset tokens or other internal secrets in normal user/session/management payloads.
+
+### Removed / incompatible
+
+- Direct construction of `new Objectiveweb\Auth($pdo, ...)`; instantiate `DBAuth` or `BasicAuth` instead.
+- `Objectiveweb\Auth\AuthController` (old class path), `PasswordMismatchException`, legacy `src/password.php`, and the 0.1.x MySQL-only query format.
+- Implicit ownership of application-managed relations and implicit OAuth account linking based on email.
+- Legacy plaintext password-reset token storage/consumption.
+
+### Deferred / not included
+
+- Built-in rate limiting is intentionally excluded. Deployments **must** configure throttling at the reverse proxy, gateway, WAF or application middleware. Planned non-SQL pluggable throttling: [#2](https://github.com/objectiveweb/auth/issues/2).
+- Acting as an OAuth2/OIDC identity provider, JWT signing/JWKS: [#3](https://github.com/objectiveweb/auth/issues/3).
+- WebAuthn/passkeys, TOTP and MFA: [#4](https://github.com/objectiveweb/auth/issues/4).
+- Refresh-token rotation, device/session management and advanced audit sinks: [#5](https://github.com/objectiveweb/auth/issues/5).
+
+See [release notes](docs/RELEASE-0.2.0.md) for a concise announcement and the [upgrade guide](docs/UPGRADING-0.2.0.md) for required migration steps. This entry is **unreleased** until the PR is merged and a release tag is published.
+
+## 0.1.x — Legacy series
+
+The previous public API used a concrete, PDO-backed `Objectiveweb\Auth`, a single `ow_auth` user table with a `username` column, `Objectiveweb\Auth\AuthController` and PHP 5.3-era dependencies. This entry describes the legacy series for comparison; its individual release dates and tag history are not reconstructed here.