Release 0.2.0

[GuilhermeBarile]

Release 0.2.0

This is a breaking rewrite of the package compared with master / 0.1.x. It introduces a provider-based auth architecture, database-backed roles and relations, OAuth/session hardening, a reusable user-management API, and modern CI/test coverage.

No compatibility or migration path from previous releases is provided for this release.

Breaking changes

• PHP requirement is now >=8.2 (previously >=5.3).
• Objectiveweb\Auth is now an abstract provider contract instead of a PDO-backed concrete implementation.
• Direct PDO/MySQL-specific persistence in Auth has been removed.
• Database authentication now lives in Objectiveweb\Auth\DBAuth and uses objectiveweb/db ^0.8.0.
• BasicAuth is now a complete in-memory provider for tests/dev/small setups.
• The old Objectiveweb\Auth\AuthController was replaced by controllers under Objectiveweb\Auth\Controller\*.
• PasswordMismatchException was removed; authentication failures use the current auth/user exception model.
• The legacy password compatibility file (src/password.php) was removed.
• Composer PSR-4 autoloading is now scoped to Objectiveweb\Auth\.
• The user model changed from a single username-centric record to users plus provider credentials (provider + uid).

Provider architecture

DBAuth

Added DBAuth as the database-backed provider:

• user registration, lookup, update and deletion;
• password login and password reset;
• multiple credentials per user;
• configurable login and recovery providers;
• credential creation, rename and deletion;
• UUID generation;
• account lifecycle via disabled_at;
• token expiration via token_expires_at / configurable TTL;
• role storage and lookup;
• managed many-to-many relations;
• authorization relations/delegations;
• eager relation hydration;
• audit, invitation/reset and deletion-guard callbacks;
• database prefix compatibility through objectiveweb/db;
• portable role lookup without database-specific GROUP_CONCAT.

BasicAuth

Added a full in-memory provider implementing the same practical contract as DBAuth:

• registration/login/password reset;
• querying and user updates;
• credential management;
• roles;
• lifecycle state;
• token handling;
• deletion guards;
• managed-relation validation;
• consistent credential rename normalization and metadata preservation.

Authentication and session security

• Session IDs are regenerated when authentication is established.
• Password and OAuth login share the same session-establishment path.
• Suspended users cannot authenticate.
• Existing sessions are revalidated so role/lifecycle changes take effect on protected requests.
• Public user payloads are centrally sanitized so password hashes, reset tokens and token-expiry internals are not exposed.
• Registration, reset, query, invitation callbacks and duplicate-credential errors now return sanitized user data.
• Password-reset tokens are stored hashed and support expiration.
• Random token generation now uses cryptographically secure randomness.

Authorization

Added role- and relation-based authorization:

• Auth::ANONYMOUS, AUTHENTICATED and ALL access markers;
• RequireRole router middleware;
• role-aware session revalidation;
• user_can() checks for global roles, delegated users and arbitrary resource relations;
• resource-ID listing for relation abilities;
• configurable ability- or role-based relation mappings;
• eager relation loading scoped to the current subject user;
• managed relation synchronization with validation callbacks.

User-management API

Added Objectiveweb\Auth\Controller\UserController, protected by the admin role, with support for:

• paginated/searchable user listing;
• role and status filtering;
• whitelisted sorting;
• user detail responses;
• user creation/invitation;
• profile and role updates;
• credential create/rename/delete;
• suspend/activate;
• password-reset and invite actions;
• managed relation updates;
• guarded deletion and relation cleanup.

Management hardening includes:

• JSON + session-bound CSRF token enforcement for HTTP writes;
• prevention of self-deletion/self-suspension;
• prevention of removing the current user's own admin role;
• prevention of deleting/suspending the final active administrator;
• suspended admins are not counted as active administrators;
• strict role payload validation;
• credential-only fields such as provider / profile are rejected on normal user updates;
• secret fields are removed from management responses.

Auth controller

The new Objectiveweb\Auth\Controller\AuthController separates authentication concerns from admin user management and supports:

• registration with configurable registration scope;
• login/logout;
• current-user/session responses;
• password recovery/reset tokens;
• callbacks for registration/recovery flows.

OAuth

Added/reworked OAuthController with:

• external provider authentication;
• provider credential linking;
• email-based linking to an existing user;
• linking OAuth credentials to an already authenticated user;
• suspended-user enforcement;
• session-ID regeneration;
• single-use OAuth state;
• state cleanup on success, invalid callbacks and provider errors;
• no OAuth state logging;
• configurable explicit redirectUri with request-derived fallback;
• safer forwarded-protocol handling.

Database schema and migrations

Added bundled Phinx migrations for the default DBAuth model:

• user;
• user_credentials;
• role;
• user_roles;
• delegations.

The default user schema includes:

• unique UUID;
• password;
• name/image;
• reset token + expiration;
• lifecycle disabled_at;
• creation timestamp.

Credential schema includes provider/UID identity, profile, token, last-login and creation fields.

Migrations intentionally use logical table names and remain compatible with application-level Phinx/database prefixes.

Correctness fixes

• Eager relation hydration now keeps the subject-user constraint and cannot include another user's row for a shared target.
• Role-user lookup now works across SQLite/MySQL/PostgreSQL without GROUP_CONCAT.
• Role lookup preserves all roles for returned users.
• Role lookup carries lifecycle state so active-admin protection is accurate.
• BasicAuth credential rename normalizes before duplicate checks and preserves metadata.
• Managed relation validation runs before mutation.
• Provider behavior is aligned more closely between BasicAuth and DBAuth.

Tooling and dependencies

• Added objectiveweb/db ^0.8.0.
• Added Phinx for development/migration testing.
• Updated PHPUnit from 4.x to 10.x.
• Fixed the Composer support/issues URL.
• Replaced Travis CI with GitHub Actions.
• Added composer validate --strict.

CI and tests

GitHub Actions now runs:

• PHPUnit on PHP 8.2, 8.3, 8.4 and 8.5;
• strict Composer validation;
• PostgreSQL 16 migration execution;
• Phinx migration status verification;
• migrated-schema verification;
• PostgreSQL execution coverage for portable role lookup.

The test suite now includes dedicated coverage for:

• AuthController;
• BasicAuth;
• DBAuth on SQLite;
• OAuth callbacks/linking/state/session behavior;
• RequireRole middleware;
• UserController;
• prefix-aware DB access;
• roles and lifecycle behavior;
• credentials;
• password reset;
• managed/eager relations;
• public-user secret sanitization;
• final-active-admin protection;
• PostgreSQL migrations and role lookup.

Documentation

README was rewritten for the 0.2.0 architecture and now documents:

• DBAuth and BasicAuth setup;
• required/default schema;
• credentials and providers;
• roles and relation authorization;
• managed relations;
• callbacks and lifecycle configuration;
• password reset;
• OAuth configuration;
• user-management API and CSRF requirements.