[tyrsson]

Closes #28

What this does

UserRepositoryInterface extends Mezzio\Authentication\UserRepositoryInterface and narrows
authenticate(). The side effects (security audit) and the account-state policy move off the
persistence layer onto the bus, so the repository verifies and the handler decides.

Field-name fixes

Two defects in the field-name handling that landed with this PR, fixed in the final commit.

authentication.username carries one meaning across three readers: Mezzio's form field name, the POST body key LoginMiddleware reads, and the SQL column UserRepositoryFactory hands to UserRepository. Two readers disagreed with the rest.

The login template hardcoded name="email" and name="password" because LoginHandler never passed the configured names. Set the key to a non-email value and the form posted a field nothing read, so the middleware fell through with no error and no flash message. The handler now resolves both names through Configuration and passes them to the template.

UserRepositoryFactory read the key raw, without the fallback Configuration::getUsernameFieldName applies when the value is absent, empty, or not a string. ConfigurationTest asserted that fallback while the SQL-building path ignored it. The factory now goes through the accessor. Analyze had baselined the resulting possibly-undefined-array-key finding; it no longer fires and the entry is removed.

Verified end to end against the running app with MySQL and Mailpit:

• Shipped config renders the credential input as name=email type=email with an Email label.
• With authentication.username set to user_name and authentication.password set to pass, the same page renders name=user_name type=text autocomplete=username and a Username label, with the password input renamed to pass.
• A real login POST against a throwaway account returns 302 to / and writes one security log row, confirming the template and the middleware agree at runtime.

Audit logging for the set-password and verification steps

Both steps changed state with no audit row. Setting a password wrote a new hash, activated the account, cleared the verification token and cleared the password-required flag. Following a verification link activated an account in the registration flow. Neither reached the log table.

Each step now records one security-channel entry per attempt, matching the doctrine AuthenticateUserHandler already documents. The dispatcher is injected into ProcessSetPasswordMiddleware and ProcessVerifyEmailMiddleware, and the account under change goes in the context.

The identity column is filled from the request principal by webware-log's middleware, and the visitor here holds a token rather than a session, so user_identifier is normally Guest and the subject of the change is in the context JSON.

The redirect from a verification link to the set-password form is deliberately not audited. It changes no state, and a mail client may prefetch the link, which would fill the table with clicks nobody made.

Verified against the running app with the log table emptied and the whole workflow driven over HTTP:

step	result
admin signs in	1 security row
POST /admin/user/create	1 app row, user_identifier is the admin
GET /user/verify.email/{token}	302 to the set-password route, no row
POST /user/set.password/{token}	1 security row naming the account, 302 to sign-in
the new user signs in	1 security row

The set-password row reads Probe SetPw set a password and activated their account. with {"email":"...","userId":13} in the context, and the account ends active=1, passwordSetRequired=0.

The same commit raises the webware/webware-log floor to ^2.0.0-alpha.4. That release resolves the identity field against the authentication configuration and prefers webware's user contract over mezzio's; usermanager supplies that configuration, so it has to ship against a version that reads it.

Commits

Three commits, in order:

1. refactor: honor the Mezzio authentication repository contract - the work described below.
2. chore(deps): bump webware/webware-tools to 1.0.0-rc.6 - raises the floor to the release that pins Mago 1.57.0 and drops the centre override of preserve-breaking-member-access-chain-first-method-on-same-line.
3. chore: apply mago 1.57.0 formatting - the mechanical output of that formatter across 86 files, 6 in src and 80 in test.

Reading 2 and 3 first is the quickest route in. Neither changes behavior, and the formatting commit is whitespace only: with every whitespace character stripped, each file compares identical to its previous revision. The 1.57.0 formatter needs two passes on LoginMiddleware before format --check is clean, which is the upstream member-access chain idempotency family, mago #2475 and #2529.

Tooling side, reviewed and released separately: webinertia/webware-tools#57, tagged 1.0.0-rc.6.

The contract

The narrowed return is (Webware\Core\UserInterface&User)|null. Webware\Core\UserInterface
already extends Mezzio\Authentication\UserInterface, so the narrowing is a true subtype and is
legal covariance. This restores the shape the interface carried before 8c106ff in the IMS
application, where the docblock read "Narrows the return type from the parent interface".

ConfigProvider aliases Mezzio\Authentication\UserRepositoryInterface to UserRepository.
Mezzio\Authentication\ConfigProvider declares no service for that name, so the alias competes
with nothing. A host can then type against either interface and drop a hand-rolled Mezzio
repository without touching type hints, while this component replaces the authentication workflow.

Where each responsibility landed

Concern	Before	After
Credential verification	UserRepository::authenticate()	unchanged, still the repository
Security audit (4 LogEvent dispatches)	UserRepository	AuthenticateUserHandler
Account-state policy	UserRepository	AuthenticateUserHandler
Result mapping	handler, pass-through	handler owns it
Request-body field names	hardcoded email / password in LoginMiddleware	authentication config via Configuration
Failure logging	duplicated (repository + middleware)	one record, one channel

UserRepository no longer takes a dispatcher; AuthenticateUserHandlerFactory resolves it instead.
mezzio/mezzio-authentication becomes a direct require. It was already resolved transitively, so
the lock records it as direct with no version change.

Behavior changes, in full

1. An inactive account with a wrong password now reports InvalidCredentials, not NotActive.
   The state check runs after verification, so the ordering is verify-then-policy. The previous
   ordering returned NotActive for any password against a deactivated account, which confirmed
   account state without proving the password. A correct password on an inactive account still yields
   NotActive and still shows the activation hint. This is the only change to an existing outcome.
2. authenticate() rejects a null or empty password before querying. password_hash('') is a
   real hash and password_verify('', $hash) returns true, so an account stored with an empty
   password would otherwise authenticate on an empty password. The guard also means a null password
   costs no query. Mezzio's contract permits a credential-only token lookup; this implementation does
   not provide one, and the interface docblock now says so.
3. MessageStatus::Failure marks every attempt that must not establish a session, including a
   denied inactive account whose password verified. AuthenticationResult::status carries the reason.
   Success now means a session may be written. Previously every outcome reported Success, so a
   failed login was indistinguishable from a successful one at the status level.
4. LoginMiddleware lost its RequestMethodInterface::METHOD_POST guard. The route is registered
   with $routeCollector->post(), so no other verb can reach it.
5. POST body field names come from authentication.username and authentication.password.
   These keys have shipped since the beginning and had no runtime reader until now. webware-log's
   PhpDbHandlerFactory reads authentication.username independently, so that key also feeds the
   log user_identifier column.

Explicitly not changed

• AuthenticationStatus and AuthenticationResult keep their shape and stay the payload contract.
• checkStatus() and the CheckUserActiveQuery identity path are untouched.
• The session payload contract and toArray() / populate() round trip are untouched.
• authentication.redirect still has no reader. Wiring PhpSession would mean implementing
  Mezzio\Authentication\AuthenticationInterface, which is a new class and out of scope here.

Verification

Gate	Result
mago fmt	clean
mago lint	no issues, 0 new baseline entries
mago analyze	no issues, 0 new baseline entries
mago guard	no issues
phpunit unit	440 tests, 1339 assertions, OK
phpunit integration	6 tests, 12 assertions, OK

Both baseline files are unchanged. The unit count rose from 439 to 440 with the null-password query
assertion, which checks preparedSqlObjects is empty rather than inferring "no query" from the return
value.

Related

• refactor: drop HttpMethodProcessorTrait from single-verb, single-route admin middleware #97 filed: HttpMethodProcessorTrait is redundant on three single-verb admin middlewares. Found
  while auditing this work; deliberately not folded in.
• fix: registration accepts a one-character password (no length or strength rule) #29 tracks the registration filter having no password length or composition rule.
• The empty-password probe behind change 2 also exposed that SetPasswordDataFilter declares
  MINIMUM_LENGTH = 12 yet accepts an empty password, because Laminas validators skip empty input.
  Configuring the minimum is filed separately.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!