<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\OAuth;

/**
 * Abstraction over "is a fully-authenticated JTL backend admin present right now?". The consent
 * step of the authorize endpoint gates token issuance on this being true (the locked decision:
 * approval == shop backend-admin login, mirroring podQuery). Kept as an interface so the authorize
 * handler is unit-testable without the shop runtime.
 */
interface AdminSession
{
    /** True only when a backend admin is logged in AND has satisfied 2FA. */
    public function isAuthenticated(): bool;

    /**
     * The `tadminlogin.cLogin` of the admin {@see self::isAuthenticated()} just verified, or null
     * when there is none (or it could not be read). Decision Q1 binds the issued token to this
     * value so the backend-action invoker can later act as exactly that admin
     * ({@see \Plugin\tnt_mcp\src\Mcp\Backend\BackendIdentityFactory}).
     *
     * Only meaningful **after** `isAuthenticated()` has been called — the backend session is opened
     * there and nowhere else.
     */
    public function approvingLogin(): ?string;

    /** URL of the backend login screen to bounce an un-authenticated approver to. */
    public function loginUrl(): string;
}
