/ 
PAGI-FastAPI-v1.7.0
/ PAGI::FastAPI::Middleware::BotProtection

NAME

PAGI::FastAPI::Middleware::BotProtection - Asynchronous Proof-of-Work Bot Protection Middleware for PAGI::FastAPI

VERSION

Version v1.7.0

SYNOPSIS

use PAGI::FastAPI;

my $app = PAGI::FastAPI->new();

# Register bot protection middleware
$app->add_bot_protection(
    difficulty => 3,
    secret     => $ENV{BOT_PROTECTION_SECRET} // die("BOT_PROTECTION_SECRET is required"),
    ttl        => 300,
);

DESCRIPTION

PAGI::FastAPI::Middleware::BotProtection integrates cryptographic Proof-of-Work bot mitigation into PAGI::FastAPI application request pipelines.

When active, incoming requests without a valid X-Bot-Challenge and X-Bot-Nonce header are rejected with an HTTP 401 Unauthorized response accompanied by challenge parameters in the response headers. Real client environments (such as web browsers executing background JavaScript) solve the puzzle and retry the request, bypassing automated bots and naive scrapers.

CONSTRUCTOR

new(%options)

Creates a new instance of PAGI::FastAPI::Middleware::BotProtection.

Accepted options:

  • secret (required)

    A non-empty string used as the HMAC key to sign and verify generated challenges.

    Security Note: Keep this value secure and avoid using hardcoded default strings in production environments.

  • difficulty (optional)

    An integer specifying the required leading zero bits (or hexadecimal zeros) for the Proof-of-Work solution. Defaults to 3.

    Higher values exponentially increase the CPU time required for the client to generate a valid nonce, while lower values reduce client computation overhead.

  • ttl (optional)

    The time-to-live duration for issued challenges, in seconds. Defaults to 300 (5 minutes).

    Challenges presented after this time window has elapsed will be rejected as expired, requiring the client to request a fresh challenge.

  • trust_proxies (optional)

    Boolean flag indicating whether to trust incoming proxy headers for client IP resolution. Defaults to 0 (false).

    When set to 0, the middleware extracts the client IP strictly from the direct TCP connection socket, ignoring client-supplied headers. When set to 1, the middleware parses the first IP from the X-Forwarded-For header if present.

    Security Note: Only set trust_proxies to 1 when running behind a trusted reverse proxy (such as NGINX, HAProxy, or AWS ALB) that strips or overwrites incoming client header values.

METHODS

pow

my $pow = $mw->pow;

Returns the underlying PAGI::FastAPI::BotProtection::ProofOfWork instance managed by this middleware.

This accessor exposes the Proof-of-Work engine directly to callers, allowing custom challenge creation (via create_challenge), manual verification (via verify), or direct inspection during testing and advanced application integrations.

HEADERS

The middleware inspects and sets the following HTTP response/request headers:

  • x-bot-challenge (Request/Response)

    The HMAC-signed challenge token string issued by the server.

  • x-bot-difficulty (Response)

    The integer difficulty level assigned to the active challenge.

  • x-bot-nonce (Request)

    The integer solution nonce computed by the client.

SEE ALSO

PAGI::FastAPI::BotProtection::ProofOfWork, PAGI::FastAPI

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PAGI::FastAPI::Middleware::BotProtection

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).