The Escena Viva User model has been sitting there since lesson 07-02 with its email, its name and its role — attendee, organizer, administrator — and no password field at all. That was not an oversight: it was a reserved gap. In this lesson we fill it with the rigor it deserves, because password storage is the one place where a mistake goes unnoticed until it becomes a newspaper headline.

We will see why a fast hash is useless, what bcrypt actually does, how to choose its cost factor by measuring, and how to write POST /auth/register and POST /auth/login without leaking which e-mails exist or how long each branch of the code takes. We will finish with what is most often done badly: verification and recovery tokens.

1. Why passwords are never stored in the clear
2. What a password hash is
3. bcrypt, scrypt and Argon2
4. bcrypt in practice
5. The native alternative: crypto.scrypt
6. Completing the User model
7. Password policy and the zod schema
8. POST /auth/register and user enumeration
9. POST /auth/login and constant time
10. Attempt limiting and logging
11. E-mail verification and recovery
12. Common mistakes, exercises and conclusion

Imagine the escena_viva database leaks: a badly permissioned backup, a SQL injection, a disgruntled employee. If there is a password column holding the raw text, three things happen: every account is compromised, including those of organizers and administrators; accounts on other services are compromised too, because people reuse passwords (Lucía's e-mail and her password get tried automatically on dozens of sites: that is credential stuffing); and the passwords remain valid until each person changes them one by one.

Encrypt them with a key? No good either. Encryption is reversible by design: there is a key that returns the original, that key lives on the server, and whoever steals the database can usually steal the server too. Besides, there is no legitimate reason to recover a password: the server only needs to check whether the one just supplied is the right one. What about a hash like MD5 or SHA-256? It is irreversible, yes, but far too fast:

Speed is a virtue for verifying files and a disaster for passwords: what makes the server fast makes the attacker fast, and the attacker has GPUs. Add that an unsalted hash of a common password is precomputed in public rainbow tables (5f4dcc3b5aa765d61d8327deb882cf99 is password in any search engine), and that two users with the same password would produce identical hashes, which is a leak in itself.

A password hash (or key derivation function) is designed with three deliberate properties:

1. It is slow on purpose: on the order of 100–500 ms. The legitimate user does not care; the attacker trying millions of combinations is ruined by it.
2. It uses a unique salt per user: a random string stored alongside the hash. It defeats rainbow tables and makes identical passwords produce different hashes. The salt is not secret: its job is uniqueness.
3. It has an adjustable cost factor: hardware improves every year, the parameter is raised, and the algorithm keeps serving for a decade.
4. The best ones add memory cost, so that throwing lots of GPU cores at it in parallel is not enough.

A reasoned recommendation: if you are starting today and can add the argon2 dependency, use Argon2id, which resists specialized hardware better thanks to its memory cost; if you need zero native dependencies, crypto.scrypt already ships with Node and is perfectly defensible. In Escena Viva we use bcrypt because it is what you will find in the vast majority of existing code, its API explains itself without noise, and its security is adequate with a well-chosen cost. What matters is the model; switching algorithms will be a change confined to a single module, and that is how we will write it. Never acceptable: MD5, SHA-1, "salted SHA-256" or any homemade invention based on concatenating and rehashing.

bcrypt compiles a native module; if that complicates your deployment (minimal containers, serverless functions), bcryptjs is the pure JavaScript implementation, API-compatible and about three times slower.

A bcrypt hash explains itself:

That is why bcrypt.compare does not need you to pass the salt or the cost: they are inside the hash. And that is why raising the cost does not invalidate old hashes: each one is verified with its own.

The cost factor is logarithmic: 12 means 2^12 = 4096 iterations and each point doubles the time. Rule of thumb: the largest value that keeps login below roughly 250 ms on your production hardware. Measure it, do not copy it:

Why constant-time comparison matters. In Module 3, with Buffers, we met crypto.timingSafeEqual: an ordinary comparison (===) stops at the first differing byte, so the elapsed time reveals how many bytes matched, and by repeating the measurement thousands of times a secret is reconstructed byte by byte. bcrypt.compare always compares the full 60 characters; the same logic will apply to the tokens in section 11.

Notice the detail almost nobody includes: storing the parameters next to the hash, which is exactly what bcrypt does for you. Without them, raising N would invalidate every previous hash.

select: false turns "do not leak the hash" into the default behavior instead of a discipline you have to remember; the only place that will ask for it explicitly is the login. lowercase: true avoids the subtle bug of ending up with two accounts for the same e-mail: technically the local part is case-sensitive, but no real provider exploits that, and normalizing is what users expect.

For twenty years the rule was "8 characters with an uppercase letter, a digit and a symbol". NIST changed its mind (SP 800-63B) because the data showed those rules produce Summer2024! everywhere: short, predictable passwords that are hard to remember and end up written on a sticky note.

Without .strict(), a body containing "role":"administrator" could end up creating an administrator if somebody writes new User(req.body): that is mass assignment, and we come back to it in 08-06. The check against breached-password lists (Have I Been Pwned) is done with k-anonymity — you send the first 5 characters of the SHA-1 and filter locally, never revealing the password — and although we do not implement it here, in production it has one of the best cost/benefit ratios around.

Go over what it does not do: it does not return the created user, it does not return the hash, it does not say whether the e-mail already existed, and it does not accept the whole body. Four deliberate omissions. The routes, in src/routes/authentication.js → { createAuthRoutes }, chain the rate limit and module 6's validate(schema, VALID_SOURCES.BODY) before each controller.

Answering "that e-mail is already registered" looks friendly and is an information leak: it lets an attacker confirm which addresses have accounts before launching credential stuffing, and in sensitive services it reveals membership. It leaks through four channels and all four have to be closed:

The honest trade-off: this hurts usability, and somebody who signed up a year ago gets no clear warning. The correct solution is to let the e-mail clear it up: if the account already exists, send a message saying "somebody tried to register with your address; if that was you, here is the link to recover it". An attacker who does not control the mailbox sees nothing; the legitimate owner does. Deciding is a judgment call: on a recipe forum, a clear 409 is defensible; on a platform holding purchase data, it is not.

We add the errors to src/errors.js, following the module 6 pattern:

We extend the STATUS_BY_CODE table in src/middleware/errors.js with NOT_AUTHENTICATED: 401, NO_PERMISSION: 403 and TOO_MANY_REQUESTS: 429. That way a failed login returns the usual format:

Slow hashing makes the attack expensive per password tried; rate limiting makes it expensive per attempt. You need both:

Beware of account lockout: if you lock an account after N failures, you have created a denial of service against any user whose address is known; an increasing delay, a CAPTCHA past a threshold and an e-mail warning are preferable. In 08-06 we tune the limits per route type and explain why an in-memory store is no good with several processes.

What gets logged: timestamp, requestId (M6), e-mail or user id, outcome and a generic reason, IP address and user agent. What never does: the password — not even hashed — the stored hash, session, access or recovery tokens, and the full request body. The most common real-world mistake is not writing console.log(password), it is dumping the entire request in a debugging middleware or an error reporter; that is why a centralized list of redacted fields pays off: password, currentPassword, token, authorization, cookie.

Both flows use the same primitive: a single-use token sent by e-mail. Four rules, no exceptions:

1. Cryptographically random, not Math.random() and not a version 1 UUID: randomBytes(32).
2. Stored hashed (SHA-256 is enough: the token already has 256 bits of entropy, no slowness required), so whoever steals the database cannot use the pending tokens.
3. Expires soon: 1 hour for recovery, 24 h for verification.
4. Single use: deleted when consumed. And on use, existing sessions and refresh tokens are invalidated: if somebody had signed in with the stolen password, the change must throw them out.

The EmailToken model stores userId, type (verification or recovery), tokenHash (unique) and expiresAt with an { expireAfterSeconds: 0 } index, so that MongoDB deletes expired documents on its own with no cleanup job needed.

And changing the password while signed in, which always requires the current one:

• Hashing on the client and sending the hash. It does not help: the hash becomes the password, and whoever steals the database authenticates with it directly. The password travels in the clear inside TLS and is hashed on the server.
• A single shared global salt. The salt is unique per user. An extra application-wide secret (pepper) is a valid layer, but it never replaces the salt and it complicates rotation.
• Storing the password "temporarily" in a field, which ends up in a backup and in a log; or forgetting select: false and returning the whole user in a JSON response, the quietest way there is to leak hashes.
• Truncating silently because of the 72-byte limit. Two long passphrases sharing a beginning would become equivalent.
• Tip: make hashPassword/verifyPassword the only place that knows about the algorithm — migrating to Argon2 will mean changing one file — and when you raise the cost, take advantage of the login to rehash whenever the password verifies successfully: a transparent migration, with nothing asked of the user.

This controller has five security flaws. Find them and explain each one.

Write verifyAndUpgrade(user, plainPassword): it verifies the password and, if the password is correct but the hash uses a cost lower than configuration.bcryptCost, regenerates and saves it. Hint: the cost is inside the hash itself, between the second and third $.

List, in order, the steps of POST /auth/recover/:token, which sets a new password, stating for each one which attack it prevents.

Exercise 1

1. User.create(req.body): mass assignment; a body containing "role":"administrator" creates an administrator. The fields must be pulled out one by one from req.validatedData.
2. SHA-256 as a password hash: fast and unsalted, vulnerable to GPUs and to rainbow tables. It must be bcrypt/scrypt/Argon2.
3. console.log of the plaintext password: it stays in the logs forever.
4. res.json(user): returns the complete document; with neither select: false nor toJSON, it exposes the hash and internal fields.
5. No prior validation: no length policy, no e-mail normalization, no duplicate control; on top of that it answers 201, revealing whether the address already existed (enumeration). Bonus flaw: the user is created without a passwordHash and saved in two steps; if the second save() fails, an account is left with no credential.

Exercise 2. The login is the only moment when the server legitimately knows the plaintext password, so it is the only possible moment to rehash.

Exercise 3

Escena Viva now has a real credential. We know why a password is never stored in the clear, encrypted or hashed with SHA-256; what a password hash does — slow, salted, with an adjustable cost — and why bcrypt keeps the variant, the cost and the salt inside the hash itself. We measured the cost factor instead of copying it, completed the User model with passwordHash and select: false, written a .strict() zod schema with a modern policy, and built a POST /auth/register and a POST /auth/login that leak which e-mails exist neither through the message, nor through the code, nor through the timing. And we got right the part that most often goes wrong: single-use tokens, random, hashed in the database and with an expiry.

But look at how login ends today: we know it is Lucía… and we do nothing with that information. The next request arrives anonymous all over again. In the next lesson, Sessions and Cookies with Passport.js, we solve it the classic way: a random session identifier in an HttpOnly cookie, the state on the server, express-session with the options that really matter, the regeneration that prevents session fixation, Passport with its local strategy, and the CSRF protection that cookies demand in exchange for their convenience.