<?php

declare(strict_types=1);

namespace apexl\Io\modules\user\interfaces;

/**
 * A pluggable second-factor method (Plan 007 §5.2). V3.0 ships a single TOTP
 * implementation; a future WebAuthn method is a new implementation behind this
 * same contract, not a new package. The service owns the entity lifecycle
 * (create/activate/lockout) — a method only provides the primitives.
 */
interface TwoFactorMethodInterface
{
    /** Stable name persisted in `user_two_factor_methods.type` (e.g. 'totp'). */
    public function getMethodName(): string;

    /** Generate a fresh shared secret to enrol with. */
    public function generateSecret(): string;

    /** The `otpauth://` provisioning URI for the given account label + secret. */
    public function provisioningUri(string $accountLabel, string $secret): string;

    /** A scannable QR image of the provisioning URI, as a data URI. */
    public function qrCodeDataUri(string $accountLabel, string $secret): string;

    /**
     * Verify a user-supplied code against the secret, tolerating clock drift by
     * `$discrepancy` periods either side.
     */
    public function verify(string $secret, string $code, int $discrepancy = 1): bool;
}
