NAME

PAGI::Middleware::Auth::Bearer - Bearer token authentication middleware

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'Auth::Bearer',
        secret => 'your-jwt-secret',
        algorithms => ['HS256'];
    $my_app;
};

# In your app:
async sub app {
    my ($scope, $receive, $send) = @_;

    my $auth = $scope->{'pagi.auth'};
    my $user_id = $auth->{claims}{sub};
}

DESCRIPTION

PAGI::Middleware::Auth::Bearer validates Bearer tokens in the Authorization header. It supports JWT (JSON Web Tokens) with HMAC-SHA256 signatures.

CONFIGURATION

• secret (required for JWT)

  Secret key for JWT signature verification.

• algorithms (default: ['HS256'])

  Allowed JWT algorithms.

• validator (optional)

  Custom token validator coderef. Receives ($token) and returns claims hashref or undef. If provided, bypasses built-in JWT validation.

• realm (default: 'Bearer')

  The authentication realm for WWW-Authenticate header.

• paths (optional)

  Arrayref of path patterns to protect.

SCOPE EXTENSIONS

This middleware adds the following to $scope when authentication succeeds:

• pagi.auth

  Hashref with authentication info:

  {
      type   => 'bearer',
      token  => 'the-raw-token',
      claims => {
          sub => 'user-id',
          exp => 1234567890,
          # ... other JWT claims
      },
  }

JWT SUPPORT

Currently supported algorithms:

• HS256 (HMAC-SHA256)

Standard JWT claims checked:

• exp - Expiration time

• nbf - Not before time

SEE ALSO

PAGI::Middleware - Base class for middleware

PAGI::Middleware::Auth::Basic - HTTP Basic authentication