bext-plugin-auth-jwt

JWT authentication middleware with automatic refresh and RBAC.

Handles token generation, validation, refresh flows, and role-based access control. Supports RS256, HS256, and ES256 algorithms.

Install

bext plugin add auth-jwt

Config

[plugins.auth-jwt]
secret = "$JWT_SECRET"
algorithm = "HS256"
expiry = "1h"
refresh_expiry = "7d"

Usage

The plugin protects routes matching your configured patterns. Access the decoded token in route handlers via `ctx.auth`.

Routes are protected by default. To make a route public, add it to the `public_routes` array:

public_routes = ["/", "/login", "/api/health"]

Refresh flow

When a token expires, the plugin checks for a valid refresh token in the `x-refresh-token` header. If present and valid, it issues a new access token and attaches it to the response as `x-new-token`. Your client can read this header and update its stored token transparently.

RBAC

Define roles in your config and check them in handlers:

[plugins.auth-jwt.roles]
admin = ["read", "write", "delete"]
editor = ["read", "write"]
viewer = ["read"]

In your route handler, `ctx.auth.role` contains the user's role and `ctx.auth.permissions` is the resolved permission array.