<?php

namespace KeyLair\TwoFactor;

/**
 * Contract every 2FA method must implement. Adding a new method later
 * (email, SMS, WebAuthn, ...) means writing one class against this
 * interface and registering it in TwoFactorManager — no changes to
 * login flow, admin UI, or the database schema.
 */
interface TwoFactorProviderInterface
{
    /** Machine-readable key stored in admin_users.two_factor_method, e.g. 'totp'. */
    public function methodName(): string;

    /** Human-readable label shown in the admin UI, e.g. "Authenticator app". */
    public function displayName(): string;

    /**
     * Begin setup for a user: generate a new secret and return whatever
     * the UI needs to show (secret, QR/manual-entry data, ...).
     *
     * @return array{secret: string, setup_data: array}
     */
    public function generateSetup(string $accountLabel): array;

    /**
     * Rebuilds the setup-screen display data (QR/manual-entry, ...) for an
     * *existing*, not-yet-confirmed secret — used to redisplay the setup
     * screen after a failed confirmation code, without generating (and
     * showing!) an unrelated new secret that wouldn't match what's actually
     * stored and being verified against.
     */
    public function buildSetupData(string $secret, string $accountLabel): array;

    /** Verify a code during setup confirmation or normal login. */
    public function verifyCode(string $secret, string $code): bool;
}
