Skip to content

JWT middleware: verify signatures, one algorithm family by default, 401 for every bad token - #24

Merged
thorwhalen merged 3 commits into
masterfrom
fix/jwt-middleware-verify-and-algorithms
Oct 13, 2026
Merged

thorwhalen merged 3 commits into
masterfrom
fix/jwt-middleware-verify-and-algorithms

Conversation

@thorwhalen

@thorwhalen thorwhalen commented Oct 13, 2026 •

Copy link
Copy Markdown
Member

Closes #21.

Changes to mk_jwt_middleware

before after
signature option options={"verify": verify} (ignored by PyJWT 2) options={"verify_signature": verify}
algorithms always ["HS256", "RS256"] with one secret keyword-only algorithms=, default ("HS256",) (as JWTPlugin)
HMAC + public-key mix silently accepted ValueError unless allow_mixed_algorithm_families=True
expired / wrong-alg / other invalid tokens jwt.DecodeError only → others became 500 any jwt.InvalidTokenError → 401
401 body echoed the token error text only, no token
401 delivery returned HTTPUnauthorized (deprecated in aiohttp) raised
Authorization header first 7 chars dropped, whatever they were Bearer scheme required (case-insensitive)
unauthenticated routes handler __name__ in {"ping", "openapi"} — any handler named ping was public aiohttp route name in public_routes= (default ("ping", "openapi"))

| verify=False | legacy option ignored, so signatures were still checked | signatures and claims really are skipped: a forged or expired token's claims land on request.token (what verify=False always claimed to do) |
| bad config (algorithms="HS256", ["hs256"], "none", empty/non-str HMAC secret, public_routes="ping") | 500 on every request, or silently rejected every token | TypeError/ValueError when the middleware is built |

Note: the 401 is now raised, so an outer middleware that turns every exception into a 500 will now also turn this 401 into a 500. That middleware would already break all of aiohttp's own HTTP exceptions.

verify stays the 2nd positional argument, so mk_jwt_middleware(secret) and mk_jwt_middleware(secret, False) keep working.

Opt-ins for the old behaviour

  • algorithms=["HS256", "RS256"], allow_mixed_algorithm_families=True restores the old algorithm list (documented as the algorithm-confusion setup).
  • A handler that relied on being public because its function was named ping/openapi must now be registered with that route name= (or have its name added to public_routes).

Tests

py2http/tests/test_jwt_middleware.py (21, real aiohttp test server on an ephemeral localhost port): valid token decoded; missing/garbage/wrong-secret/alg: none/expired/disallowed-alg tokens → 401 without echo; public route by name vs a handler named ping; mixed-family ValueError; an HS256-with-public-key forgery against an RS256 config → 401; verify=False. 9 of the 12 fail on master. Full suite: 74 passed.

Adversarial review

Fresh Opus reviewer, three passes.

  • Pass 1: SHIP-WITH-FIXES. No token forgery and no way to reach a private route without a token. Tried: alg: none/NONE, lowercase hs256, an HS256 token signed with the RSA public key, jwk/kid/crit/b64 header tricks, Bearer variants, sub-paths, HEAD/OPTIONS, 404s and unnamed routes. Confirmed and fixed:
    • Undocumented verify=False change: now in the table and the docstring.
    • The outer catch-all case: noted above.
    • Configuration errors that gave a 500 on every request (empty secret; an HS256 token against a PEM key with mixed families allowed): now caught at build or answered with 401 (PyJWTError).
    • algorithms as a string, or in the wrong case: rejected at build.
    • None in public_routes no longer opens unnamed routes.
  • Pass 2: SHIP. Nits fixed:
    • public_routes as a string is rejected.
    • A non-str/bytes HMAC secret is rejected at build.
    • The 401 text for key errors is generic, so it no longer reveals that the server's key is asymmetric.
  • Deferred to JWTPlugin (bottle) lags mk_jwt_middleware; no audience/issuer passthrough in either #25: JWTPlugin (bottle) parity, and audience/issuer passthrough.

Dependents gate (priv test-dependents py2http --transitive): py2http and extrude pass. mk_jwt_middleware has no callers outside py2http.

🤖 Generated with Claude Code

thorwhalen and others added 2 commits October 13, 2026 02:33
…hm family

mk_jwt_middleware now:
- passes options={"verify_signature": verify} (PyJWT 2 ignored the legacy "verify" key);
- takes algorithms= (keyword-only, default ("HS256",)) and raises ValueError when
  HMAC and public-key algorithms are mixed under one secret, unless
  allow_mixed_algorithm_families=True (the old ["HS256", "RS256"] default);
- answers every invalid token (expired, wrong algorithm, ...) with 401 instead of
  letting non-DecodeError exceptions become 500s, and raises the 401 rather than
  returning it (deprecated in aiohttp);
- no longer echoes the token back in the 401 body;
- requires the "Bearer " scheme;
- lets requests through without a token by aiohttp route name (public_routes=,
  default ("ping", "openapi")), not by handler __name__, so a handler that happens
  to be called "ping" is not public.

Closes #21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t, 401 for unusable keys

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… generic text for key errors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thorwhalen
thorwhalen merged commit 968859c into master Oct 13, 2026
6 checks passed
@thorwhalen
thorwhalen deleted the fix/jwt-middleware-verify-and-algorithms branch October 13, 2026 02:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

mk_jwt_middleware: legacy 'verify' option and mixed HS256/RS256 with one secret

1 participant