JWT Auth Middleware Worker

JWT Auth Middleware Worker

A production-ready Cloudflare Worker that validates JSON Web Tokens at the edge before requests ever reach your origin server. Invalid or expired tokens get an immediate 401 response — your backend never sees them. Supports RS256 and HS256 algorithms, JWKS endpoint auto-rotation, and configurable path-based rules via Cloudflare KV.

What's Included

• Edge JWT Validation — Full token verification at the Cloudflare edge: signature validation, expiration checks, issuer/audience claims, and custom claim requirements
• RS256 + HS256 Support — Verify tokens signed with RSA public keys (fetched from a JWKS endpoint) or HMAC shared secrets stored securely in Worker secrets
• JWKS Auto-Rotation — Automatically fetches and caches public keys from your identity provider's JWKS endpoint; handles key rotation without redeployment
• Path-Based Rules — Configure which routes require auth, which are public, and which need specific claims or scopes — all stored in KV for instant updates
• Structured 401 Responses — Returns RFC 7235-compliant WWW-Authenticate headers with descriptive error codes: expired, invalid_signature, missing_token, insufficient_scope

How It Works

• The Worker intercepts every request before it reaches your origin
• Public paths (configurable in KV) pass through immediately with no token check
• Protected paths extract the Bearer token from the Authorization header
• The token is decoded, its signature verified against JWKS or a shared secret, and claims are validated (exp, iss, aud, custom scopes)
• Valid requests are forwarded to origin with decoded claims injected as X-Auth-* headers; invalid requests get an immediate 401

What You Get

• src/index.js — Main Worker entry point with request routing and middleware chain
• src/jwt.js — JWT decode, signature verification (RS256/HS256), and claims validation using the Web Crypto API
• src/jwks.js — JWKS endpoint fetcher with KV-backed caching and automatic key rotation
• src/rules.js — Path matching engine that loads route rules from KV: public, authenticated, or scope-restricted
• src/responses.js — Standardized 401/403 JSON responses with proper WWW-Authenticate headers
• wrangler.toml — Pre-configured Wrangler deployment config with KV namespace and secrets bindings
• scripts/seed-kv.js — Seeds your KV namespace with default route rules, issuer config, and JWKS URL
• package.json — Wrangler CLI dependency and deploy/dev/seed scripts
• .env.example — Cloudflare account ID, API token, JWKS URL, and optional HMAC secret placeholders
• README.md — Setup guide, identity provider integration examples (Auth0, Clerk, Firebase), route rule reference, and deployment instructions

Deployment

Requirements

A Cloudflare account with Workers enabled (free tier supports 100k requests/day). Node.js 20+ for the Wrangler CLI. One KV namespace (created automatically by wrangler on first deploy). A JWT issuer — works with Auth0, Clerk, Firebase Auth, Supabase Auth, or any provider that exposes a JWKS endpoint.