jwt and jwk middlewares hardcode req.url as WWW-Authenticate realm with no configurable override, unlike bearer-auth

[Nexory]

Description

The jwt and jwk built-in middlewares produce 401 responses with a WWW-Authenticate header whose realm is unconditionally set to the full request URL (ctx.req.url):

WWW-Authenticate: Bearer realm="https://api.example.com/v1/users/42?token=abc",error="invalid_token",error_description="token verification failure"

RFC 6750 defines realm as a human-readable string that identifies the protection space — not the request URL. Reflecting the full URL here is a poor default: it conflates the request path (which varies per resource) with the realm descriptor (which should be stable and descriptive), and it produces a different realm value for every distinct URL, which is inconsistent with how realm is supposed to work.

The bearer-auth middleware avoids this by exposing a realm option (defaulting to "") that lets developers supply a fixed, meaningful string:

// bearer-auth/index.ts — line 25-26
realm?: string
// line 117
const realm = options.realm?.replace(/"/g, '\\"')

jwt and jwk have no equivalent option; their unauthorizedResponse() helper is private and always reads opts.ctx.req.url. There is no workaround short of wrapping or replacing the middleware entirely. This API inconsistency means developers using jwt/jwk cannot produce a well-formed, stable WWW-Authenticate realm value without forking the middleware.

Affected code

src/middleware/jwt/jwt.ts lines 160–173 (identical pattern at src/middleware/jwk/jwk.ts lines 170–183):

160 | function unauthorizedResponse(opts: {
161 |   ctx: Context
162 |   error: string
163 |   errDescription: string
164 |   statusText?: string
165 | }) {
166 |   return new Response('Unauthorized', {
167 |     status: 401,
168 |     statusText: opts.statusText,
169 |     headers: {
170 |       'WWW-Authenticate': `Bearer realm="${opts.ctx.req.url}",error="${opts.error}",error_description="${opts.errDescription}"`,
171 |     },
172 |   })
173 | }

Fix recommendation

Add an optional realm field to both the jwt() and jwk() options objects, mirroring what bearer-auth already does. When realm is not provided, fall back to "" rather than ctx.req.url:

// jwt options type — add:
realm?: string

// In unauthorizedResponse, replace:
`Bearer realm="${opts.ctx.req.url}"`
// with:
`Bearer realm="${opts.realm ?? ''}"`

This change is backwards-compatible. The same change should be applied to src/middleware/jwk/jwk.ts, which contains an identical copy of unauthorizedResponse.

PoC

See poc_idx0.mjs / poc_output_idx0.txt

[xu91102]

I checked this against current main and the issue description still matches the code and tests.

Current behavior I found:

Middleware	Realm source	Can override WWW-Authenticate?	Evidence
bearerAuth	options.realm, default ""	Yes, via noAuthenticationHeader, invalidAuthenticationHeader, and invalidToken wwwAuthenticateHeader options	src/middleware/bearer-auth/index.ts has realm?: string and `wwwAuthenticateHeader?: string
jwt	ctx.req.url	No override option that I can see	src/middleware/jwt/jwt.ts builds WWW-Authenticate in unauthorizedResponse() with Bearer realm="${opts.ctx.req.url}",...; src/middleware/jwt/index.test.ts asserts the full request URL in the realm.
jwk	ctx.req.url	No override option that I can see	src/middleware/jwk/jwk.ts uses the same unauthorizedResponse() pattern; src/middleware/jwk/index.test.ts also asserts the full request URL in the realm.

I also noticed the related implementation PR #4524 is still open as a draft and was last updated in 2025-11.

Before opening another implementation PR, would maintainers prefer one of these directions?

1. Add a small backwards-compatible option for jwt / jwk to configure the realm or WWW-Authenticate header, closer to bearerAuth.
2. Keep the current API and document that jwt / jwk intentionally use the request URL as the realm.
3. Continue/review feat: updated jwt and jwk to match bearerAuth middleware #4524 instead of opening a separate PR.

If option 1 is preferred, I can prepare a narrow PR with tests first.