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

The built-in JWT validation is intentionally minimal, suitable for simple use cases and development.

Supported algorithms: HS256 (HMAC-SHA256) only

Claims checked: exp (expiration), nbf (not before)

Not checked: iss (issuer), aud (audience), iat (issued at), jti (JWT ID for replay protection)

Not supported: Asymmetric algorithms (RS256, ES256), JWKS key fetching, key rotation, clock skew tolerance

For production systems requiring full JWT validation, use the validator option with Crypt::JWT:

use Crypt::JWT qw(decode_jwt);

enable 'Auth::Bearer',
    validator => sub {
        my ($token) = @_;
        my $claims = eval {
            decode_jwt(
                token   => $token,
                key     => $secret,
                verify_iss => 'https://auth.example.com',
                verify_aud => 'my-api',
            );
        };
        return $@ ? undef : $claims;
    };

See Crypt::JWT for complete JWT/JWS/JWE support including RS256, ES256, JWKS, and all standard claim validations.

SEE ALSO

PAGI::Middleware - Base class for middleware

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