irdb/ui/src/Auth/OidcAuthenticator.php

<?php

declare(strict_types=1);

namespace App\Auth;

/**
 * Thin abstraction over the concrete OIDC client. Lets us mock the
 * provider in integration tests without spinning up a real IdP.
 *
 * `authenticate()` returns the verified claims on success; the
 * implementation is responsible for redirecting to the IdP when the
 * incoming request doesn't yet carry a `code` parameter.
 */
interface OidcAuthenticator
{
    /**
     * Drive the authorization-code-with-PKCE flow.
     *
     * Behaviour:
     *  - On the first request (no `code`): emit a redirect to the IdP
     *    and call `exit`. The caller's PHP process ends inside this
     *    method — it does not return.
     *  - On the callback request (with `code`): exchange the code,
     *    verify the ID token, and return `OidcClaims`.
     *
     * Throws `OidcException` on any verification or transport failure.
     */
    public function authenticate(): OidcClaims;
}