/ 
PAGI-FastAPI-Security-v0.0.4
/ PAGI::FastAPI::Security

NAME

PAGI::FastAPI::Security - Authentication scheme building blocks for PAGI::FastAPI

VERSION

Version v0.0.4

SYNOPSIS

use PAGI::FastAPI;
use PAGI::FastAPI::Security::HTTPBearer;

my $bearer = PAGI::FastAPI::Security::HTTPBearer->new;
my $app    = PAGI::FastAPI->new(title => 'PAGI::FastAPI app');

$app->get('/items',
    dependencies => [ $bearer->depends(key => 'token') ],
    handler      => async sub ($c) {
        my $token = $c->stash->{token};
        # verify $token yourself, however you like
        return { items => [] };
    },
);

DESCRIPTION

The PAGI::FastAPI::Security comprises a compact selection of classes for the authentication scheme offered as part of the PAGI::FastAPI::Depends for the framework of PAGI::FastAPI, taking the inspiration from the fastapi.security module regarding the Python FastAPI.

In general, every class used for the authentication scheme has been extracting the credentials from the request. The classes do provide the specification of the error response where necessary (401 + WWW-Authenticate for the challenge-based types and 403 for the API keys). Nevertheless, they do not really verify the credentials, and thus token signature and password/hash verification are left to the user.

AVAILABLE SCHEMES

DESIGN NOTES

Why these don't verify tokens

Actual token validation is quite diverse: the verification of a JWT signature alone can refer to any of Crypt::JWT, Mojo::JWT, or a JWKS-fetching client, while non-transparent tokens almost always require a database or cache lookup. Putting together any of those is impractical because everyone who would download this package would need to install and configure something, and hence, following the boundaries of C exactly, all of the classes indeed go only halfway through and leave the verification to some other external library or the route handler.

$app->get('/items',
    dependencies => [
        $bearer->depends(key => 'token'),
        Depends(async sub ($c) {
            my $claims = eval { verify_jwt($c->stash->{token}) };
            unless ($claims) { $c->status(401); return { detail => 'Invalid token' } }
            return $claims;
        }, key => 'claims'),
    ],
    handler => async sub ($c) { ... $c->stash->{claims} ... },
);

Failure Contract

These classes indicate any failure in the same manner that the dependency dispatcher of PAGI::FastAPI anticipates by invoking $c->status($code) using a code >= 400 and by producing a body HashRef, delegating the responsibility of the route handler generation.

AUTHOR

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

REPOSITORY

https://github.com/manwar/PAGI-FastAPI-Security

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI-Security/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::Security

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). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0