namespace Svrnty.CQRS.Altcha.Abstractions;

/// <summary>
/// Marks a command or query as requiring proof-of-work (or equivalent
/// anti-abuse evidence) before the framework will dispatch it to the handler.
/// </summary>
/// <remarks>
/// The accompanying request type should implement <see cref="IHasAltchaSolution"/>
/// to carry the widget's solution payload. The framework's Altcha
/// authorization check (registered via <c>AddSvrntyAltcha()</c>) reads the
/// solution off the request and calls the configured <see cref="IAltchaVerifier"/>.
/// </remarks>
[AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
public sealed class AltchaAttribute : Attribute
{
    /// <summary>
    /// When <c>true</c> (default), a valid mobile-attestation token on the
    /// request satisfies the requirement without needing a proof-of-work
    /// solution. The Altcha check reads
    /// <see cref="Svrnty.CQRS.Abstractions.Security.AuthorizationCheckContext.Items"/>[<c>"mobile_attested"</c>]
    /// — when stamped <c>true</c> by an earlier check (e.g. an Apple
    /// App Attest / Play Integrity verifier), the PoW check is skipped.
    /// Set to <c>false</c> on commands where PoW must always run regardless
    /// of caller.
    /// </summary>
    public bool AllowMobileAttestationBypass { get; set; } = true;
}