br-auth-middleware

Better Route authentication middleware

Select authentication by client type, attach it as middleware, and mark every raw route as middleware-protected. Better Route 1.1 denies every raw route by default, including GET and OPTIONS.

use BetterRoute\Middleware\Jwt\Hs256JwtVerifier;
use BetterRoute\Middleware\Jwt\JwtAuthMiddleware;

$auth = new JwtAuthMiddleware(
    verifier: new Hs256JwtVerifier(
        secret: MY_PLUGIN_JWT_SECRET,
        expectedIssuer: 'https://issuer.example',
        expectedAudience: 'my-api',
        maxLifetimeSeconds: 3600
    ),
    requiredScopes: ['orders:read']
);

$router->get('/orders/(?P<id>\d+)', $handler)
    ->middleware([$auth])
    ->protectedByMiddleware('bearerAuth');

Choose the middleware

• Use JwtAuthMiddleware with Hs256JwtVerifier for first-party HS256 tokens.
• Use BearerTokenAuthMiddleware with JwtBearerTokenVerifierAdapter and Rs256JwksJwtVerifier for RS256/ES256 JWKS tokens. Follow br-jwks-jwt-auth.
• Use BearerTokenAuthMiddleware with a custom BearerTokenVerifierInterface for opaque or externally verified bearer tokens.
• Use ApplicationPasswordAuthMiddleware for server-to-server WordPress Application Password Basic authentication.
• Use CookieNonceAuthMiddleware for same-site browser requests with a logged-in WordPress cookie and X-WP-Nonce. Keep both requireNonce and requireLoggedIn enabled unless a separately reviewed design requires otherwise.

protectedByMiddleware() tells the WordPress permission callback to let the request reach the middleware pipeline. It does not add authentication by itself: the authentication middleware must also be attached. The optional name describes the OpenAPI security scheme.

JWT verification rules

• exp is required by default. Do not disable requireExpiration for normal production tokens.
• When maxLifetimeSeconds is set, both iat and exp are required and exp - iat must not exceed the limit.
• Set expectedIssuer and expectedAudience in production.
• Keep maxTokenLength bounded; the default is 8192 bytes.
• Required-scope wildcards are server-controlled. A token-supplied granted scope ending in * expands authority only when allowGrantedScopeWildcards: true; keep that opt-in off unless the issuer contract requires it.