<?php

declare(strict_types=1);

namespace Instinctor\Core\Session;

/**
 * Session/CSRF driver interface.
 *
 * On WordPress: thin wrapper over wp_create_nonce / wp_verify_nonce / check_ajax_referer.
 * On Standalone: HMAC-signed tokens with expiry, stored in instinctor_sessions.
 */

if (!defined('ABSPATH')) exit;
interface DriverInterface
{
    /**
     * Generate a CSRF token for the given action.
     * Equivalent to wp_create_nonce($action).
     */
    public function token(string $action): string;

    /**
     * Verify a CSRF token for the given action.
     * Returns true if valid, false otherwise.
     * Equivalent to wp_verify_nonce($token, $action).
     */
    public function verify(string $token, string $action): bool;

    /**
     * Verify a CSRF token and die/throw if invalid.
     * Equivalent to check_ajax_referer($action, $field).
     *
     * @param string $action  The nonce action to verify.
     * @param string $field   The POST/GET field name containing the token.
     * @param bool   $die     If true, terminate on failure (WP mode). If false, return false.
     */
    public function check(string $action, string $field = 'nonce', bool $die = true): bool;
}
