Javascript Genesis: 100 Chapters

Parameters | Parameter | Type | Required | Description | |---|---|---:|---| | verify | object | Yes | JWT verification settings | | verify.secretOrPublicKey | string \| Buffer | Yes | HMAC secret (HS*) or public key (RS*/ES*) | | verify.algorithms | string[] | No | Allowed algorithms for jwt.verify (e.g., ["RS256"]) | | verify.issuer | string | No | Expected iss claim | | verify.audience | string \| string[] | No | Expected aud claim | | verify.clockToleranceSeconds | number | No | Leeway for exp/nbf checks (seconds) | | refresh | object | No | Refresh behavior | | refresh.enabled | boolean | Default: false | Enables refresh flow on expired tokens | | refresh.onRefresh | function | Conditional | Hook invoked when token is expired and refresh is enabled | | refresh.onRefresh({ expiredToken, req }) | function return type: Promise | Conditional | Returns a new access token payload | | headers | object | No | Header parsing/format rules | | headers.authorizationScheme | string | Default: "Bearer" | Expected scheme prefix in Authorization header | | headers.authorizationHeader | string | Default: "authorization" | Header name to read from request | | attachClaimsTo | string | Default: "auth" | Request property name to store auth context | | errorResponses | object | No | Error payload customization | | errorResponses.unauthorizedBody | object | No | JSON body for 401 responses |

Code Example `js import express from "express"; import jwt from "jsonwebtoken";

function jwtAuthMiddleware({ verify, refresh = { enabled: false }, headers = {}, attachClaimsTo = "auth", errorResponses = {}, } = {}) { const scheme = headers.authorizationScheme?? "Bearer"; const headerName = headers.authorizationHeader?? "authorization";

return async function jwtAuth(req, res, next) { const authHeader = req.headers[headerName]; if (!authHeader || typeof authHeader!== "string") { return res.status(401).json(errorResponses.unauthorizedBody?? { error: "missing_authorization" }); }

const [tokenScheme, token] = authHeader.split(" "); if (tokenScheme!== scheme ||!token) { return res.status(401).json(errorResponses.unauthorizedBody?? { error: "invalid_authorization_format" }); }

const options = { algorithms: verify.algorithms, issuer: verify.issuer, audience: verify.audience, clockTolerance: (verify.clockToleranceSeconds?? 0), };

try { const decoded = jwt.verify(token, verify.secretOrPublicKey, options); // throws on invalid/expired tokens req[attachClaimsTo] = { claims: decoded, token, exp: decoded.exp, iat: decoded.iat }; return next(); } catch (err) { // Token expired: optionally refresh via hook if (refresh.enabled && err && err.name === "TokenExpiredError" && typeof refresh.onRefresh === "function") { const result = await refresh.onRefresh({ expiredToken: token, req }); if (!result?.accessToken) { return res.status(401).json(errorResponses.unauthorizedBody?? { error: "refresh_failed" }); }

// Verify refreshed token before attaching claims const decoded = jwt.verify(result.accessToken, verify.secretOrPublicKey, options); req[attachClaimsTo] = { claims: decoded, token: result.accessToken, exp: decoded.exp, iat: decoded.iat };

// Optional: expose refreshed access token to the client res.setHeader("X-Access-Token", result.accessToken); return next(); }

// Non-refreshable auth failures return res.status(401).json(errorResponses.unauthorizedBody?? { error: "invalid_token" }); } }; }

// Example usage const app = express();

const auth = jwtAuthMiddleware({ verify: { secretOrPublicKey: process.env.JWT_PUBLIC_KEY, // RS256 public key or HS secret algorithms: ["RS256"], issuer: "my-api", audience: "web", clockToleranceSeconds: 5, }, refresh: { enabled: true, onRefresh: async ({ expiredToken, req }) => { // Implement refresh strategy (e.g., validate refresh cookie/session elsewhere) // Must return: { accessToken: " ", expiresInSeconds?: number } return { accessToken: req.newAccessTokenFromSession?? null }; }, }, headers: { authorizationScheme: "Bearer" }, attachClaimsTo: "auth", });

app.get("/protected", auth, (req, res) => { res.json({ ok: true, sub: req.auth?.claims?.sub, roles: req.auth?.claims?.roles?? [] }); }); `

Response Format `json { "error

{ "error": { "code": "invalid_token | missing_authorization | invalid_authorization_format | refresh_failed", "message": "human_readable_error", "requestId": "optional_correlation_id" } } `

When the middleware succeeds, the protected handler receives verified claims on req[attachClaimsTo]:

json { "auth": { "claims": { "sub": "string", "roles": ["string"], "iss": "string", "aud": "string", "iat": 1710000000, "exp": 1710003600 }, "token": "string", "exp": 1710003600, "iat": 1710000000 } }

Notes & Best Practices - Header handling: Enforce a single scheme (Bearer) and a single header name (Authorization by default). Reject tokens with extra segments (e.g., split(" ") must yield exactly [scheme, token]). - Token refresh hook: Only refresh on TokenExpiredError. The refresh hook must return { accessToken }; the middleware verifies the refreshed JWT again before attaching claims to req. - Clock tolerance: Set clockToleranceSeconds explicitly (commonly 0-10). Large tolerances can extend acceptance windows for compromised tokens. - Error response consistency: Keep 401 payloads stable across all auth failures so clients can implement a deterministic retry/reauth flow.

Next, you can extend this middleware with route-specific authorization checks (roles/scopes) layered on top of the verified JWT claims, without changing the verification boundary.

End of chapter one. 4 more chapters and about 4,001 words in the full book.