Authentication & Passwords

In Part 4, we checked a proposed change before storing it. A valid title tells us what the user wants to save, but it does not tell us who is making the change or whether the note belongs to that account. Let’s follow those questions through a notes application in which signed-in users create and edit their own notes.

Authentication establishes which account a request represents. Authorization decides whether that account may perform an operation. Putting userId: 7 in a request body answers neither question: a caller can choose that number.

The application’s authentication subsystem verifies credentials and manages sessions; the rest of the application uses its public interface. In this example, a session is server-side state that associates later requests with an account. A cookie is a name/value pair that the browser stores and sends automatically on matching requests. We will first follow the identity that these requests establish, then examine cookies more closely in the next chapter.

Registration, login, and session endpoints

To create a note for a particular account, we first need to register and sign in. The example API accepts JSON bodies for registration and login and validates them against strict schemas. Keep the request and its returned account fields together as you follow the interaction:

An account view such as {"user":{"id":7,"displayName":"Example user"}} exposes only public account fields. The API keeps the password and session token out of JSON responses. We will return to the choice of public output fields in Chapter 5.5.

The note service uses the acting account’s ID from the resolved session, never an identity claimed in a form, query parameter, browser store or caller-supplied header. It also checks that the account owns the note before allowing an edit.

Figure 1 separates the session check that identifies an account from the ownership check that permits a note edit.

What happens to a password

Signing in asks the server to verify a password. Before tracing the rest of the request, let’s look at what the server needs to keep for that check.

Send passwords over HTTPS outside local development. Do not log them, place them in URLs, return them from the API or persist them in browser storage. Pass the entered password unchanged to the authentication subsystem; do not add trimming or normalization in the form. Any password normalization policy must be consistent at registration and verification. Email normalization is a separate account-lookup policy.

Plaintext is the original readable password. Storing it would expose every password if someone obtained the account records. Store a password hash instead: a one-way representation used to verify a submitted password without keeping the original.

Password hashing deliberately requires computing time and memory. That cost is manageable for one login but makes an attacker trying many guesses do more work for each guess. A salt is a random value included when hashing each password, so hashing the same password twice produces different stored values. Use a maintained password-hashing library to handle the algorithm, salt generation and verification. The OWASP password-storage guidance explains these protections.

Create and verify a hash

The course uses scrypt-kdf. Save this example as password-example.js. Predict the two verification results, then run it with deno run password-example.js; Deno downloads the pinned package on the first run.

import Scrypt from "npm:scrypt-kdf@4.0.0";

const parameters = { logN: 15, r: 8, p: 3 };
const storedHash = await Scrypt.kdf("hamburger with extra pickles", parameters);

console.log(await Scrypt.verify(storedHash, "hamburger with extra pickles")); // true
console.log(await Scrypt.verify(storedHash, "hamburger without pickles")); // false

Scrypt.kdf(password, parameters) creates the stored hash. The supplied parameters control the computing and memory cost; use these course settings for this example. Its result is a Uint8Array, a collection of bytes containing the hash, salt and parameters needed for later verification. Keep that complete result as the password record.

Scrypt.verify(storedHash, password) uses the stored salt and parameters to check a candidate password and returns a Boolean. The stored hash is its first argument. Both operations return promises, so the example uses await. Verification does not recover the original password. Creating another fresh hash and comparing the two stored values would fail because each creation uses a new salt.

Use these two library operations in the exercise below. Its editor supplies the import, parameters and function signatures, so you can concentrate on creating and verifying a hash.

const storedHash = await createPasswordHash("hamburger");
console.log(await verifyPassword("hamburger", storedHash)); // true
console.log(await verifyPassword("cheeseburger", storedHash)); // false

From login to authenticated note requests

We can now return to the notes workflow. Suppose the server assigns account ID 7 at registration. Follow that account from login to the creation and reading of a note. This trace focuses on account identity; Chapter 5.6 adds the checks that protect state-changing requests.

In Hono, session middleware can place a safe user in the request context as currentUser. The handler reads c.get("currentUser"), rejects a missing identity with 401, and passes the user’s ID to the note service. If the session has expired, the displayed account name cannot authorize the request.

Rejection is different from unavailability

The successful trace assumes the server could check the credentials. Now consider two failures: the password does not match, or the database cannot be reached. As with rejected and uncertain mutations in Part 4, these results give us different information.

Missing accounts and incorrect passwords receive the same public rejection message to avoid revealing account existence. If the database is unavailable, the service cannot decide whether the credentials matched. Report an unavailable operation without exposing internal details.

This type describes the credential-verification interface:

type SafeUser = {
  id: number;
  displayName: string;
};

type CredentialResult =
  | { kind: "accepted"; user: SafeUser }
  | { kind: "rejected" }
  | { kind: "unavailable" };

The login handler creates a session only for accepted. It maps rejected to 401 with {"error":{"code":"INVALID_CREDENTIALS","message":"Invalid email or password"}}, and a temporarily unavailable lookup to 503 with {"error":{"code":"UNAVAILABLE","message":"Sign-in is temporarily unavailable"}}. Returning 401 for every failure would erase this distinction.

We have followed how the server establishes an account identity. The next chapter follows what happens after login: how the browser carries the cookie, how a reload rediscovers the account, and what changes when the session expires or the user logs out.

Check Your Understanding

1. Why does a caller-supplied user ID fail to establish identity?
2. Which user fields may a resource handler receive from the trusted session boundary?
3. Why does successful login not authorize editing another person’s note?
4. Why are rejected credentials and an unavailable account lookup different results?
5. Why can two stored hashes differ even when they were created from the same password?