Better Auth

Picture a small notes app. Anyone can open its address in a browser, but each person should see only their own notes. To do that, the app has to answer two questions every time someone asks for something: who is this? and are they allowed to do this?

This course follows that notes app from its first sign-up page to a production system with email links, "Sign in with GitHub", two-step sign-in and an admin who manages users. Every idea lands on it.

1. Ana signs up with her email and a password.
2. She confirms her email by clicking a link.
3. She writes notes; only she can read them.
4. She forgets her password and chooses a new one.
5. Later she signs in with her GitHub account instead.
6. An admin can see users, and block one who misbehaves.

A hotel is a good picture. At the front desk you show your passport: that is authentication. The key card you get opens your room and the gym, but not other rooms: that is authorization. The desk checks you once; the doors check your card every time.

A credential is anything you present to prove you are who you say: a password, a code from your phone, a fingerprint. Security people group them into three kinds, called factors.

Credential

Something presented to prove identity: a password, a code, a key.

Multi-factor authentication (MFA)

Asking for two or more different factors, such as a password and a phone code.

Apps keep a user for each person: an id, an email, a name. Separately they keep the ways that person can sign in. Ana might use a password today and her GitHub account tomorrow, and both should open the same notes.

User

The record of one person in your app.

Account

One way that user can sign in: a password, GitHub, Google.

Session

One signed-in browser or device. Module 3 explains them.

Each journey looks simple and hides many traps: storing passwords safely, links that can only be used once, cookies with the right settings, limits on guessing, not revealing who has an account. One mistake can expose every user.

Better Auth is an open-source TypeScript library that does this work inside your own server. It is not a separate hosted service: your users live in your own database, and you can read every line it runs.

Three places take part: the browser (or a phone app), which shows pages; the server, a program on a computer you control that answers requests; and the database, where the server keeps data. The browser belongs to the visitor, so they can change anything in it.

• Authentication proves who someone is; authorization decides what they may do.
• Credentials come in three factors: know, have, are. MFA mixes different factors.
• A user is a person; an account is one way in; a session is one signed-in device.
• Every app with accounts needs sign-up, sign-in, sign-out, email checks, resets and often social sign-in.
• Better Auth is a library inside your server that keeps its data in your database.
• The browser is the visitor's: real checks happen on the server.

When you open a page, your browser sends a request to a server, and the server sends back a response. The rules for that conversation are called HTTP. HTTPS is the same conversation, encrypted so nobody in between can read or change it.

Method

What the request wants: GET reads, POST creates or acts, DELETE removes.

Path

Which thing on the server: /notes, /notes/42.

Status code

A number in the response saying how it went: 200 fine, 404 not found.

Header

A labelled line of extra information on a request or response.

HTTP is stateless: the server treats every request as if it had never seen you before. Ana can sign in with one request, and the very next request, by itself, says nothing about who sent it.

So after Ana proves who she is once, her browser needs something to send with every later request that says "this is still Ana". That something is almost always a cookie.

A cookie is a small named value that a server asks the browser to keep. The server sets it with a Set-Cookie header in a response. From then on, the browser adds a Cookie header with it to every request to that server, on its own.

Browsers keep sites apart by origin: the scheme (https), the host (notes.example.com) and the port (443, the HTTPS default). Two addresses have the same origin only if all three match. A site is looser: every subdomain of example.com is the same site.

• Strict: sent only when you are already on the same site. Even following a link from another site, such as your webmail, arrives without it.
• Lax: also sent when you follow a link to the site (a top-level GET), but not with forms or scripts that other sites send. The usual choice for sessions.
• None: always sent, even from other sites. Requires Secure. Only for setups that truly need it.

• A browser sends requests; a server sends responses, each with a status code and headers.
• HTTP is stateless: nothing links one request to the next by itself.
• A cookie is set with Set-Cookie and sent back with every request in Cookie.
• HttpOnly, Secure, SameSite, Max-Age, Path and Domain control who sees and sends it.
• An origin is scheme + host + port; a site includes all subdomains.
• A session cookie is as valuable as a password.

At a coat check you hand over your coat and get a ticket with a number. The ticket means nothing by itself; the attendant looks the number up. A session works the same way: after sign-in, the server saves a row saying "token k7Qx… belongs to Ana until Friday" and gives the browser the token in a cookie.

Session

A record on the server that a signed-in device points at.

Session token

The random value that names the session. Whoever holds it is signed in.

If tokens were 1, 2, 3, anyone could change their cookie to 2 and become someone else. A session token is made by a cryptographic random generator and is long enough (32 characters or more) that guessing one is hopeless, even with billions of tries.

A signature is a short code computed from a message and a secret only the server knows. Change one letter of the message and the signature no longer matches. Anyone can read a signed message, but only the holder of the secret can make a valid one.

1cookie value:  k7QxN2...pW9  .  q3Jf8a...Lw0=2               ^ the token      ^ its signature, made with the secret

The other approach puts the facts inside the token: "this is Ana, valid until 10:15", plus a signature. The server checks the signature and believes the contents without looking anything up. The common format is the JWT (JSON Web Token), said "jot".

1{2  "sub": "user_8f2c",3  "email": "ana@example.com",4  "exp": 17672256005}

A session has an end time. Many apps use a sliding window: each time you come back, the end moves later, so active people stay signed in and forgotten devices sign out on their own. Signing out deletes the session at once.

• Signing in saves a session row and sets a signed, HttpOnly session cookie.
• Each check verifies the signature, finds the row, and checks the end time.
• An optional cookie cache also keeps a short-lived signed copy of the session in a cookie, skipping the lookup for a few minutes. Module 18 weighs that trade-off.
• Plugins add bearer tokens for apps and JWTs for other services, when you need them.

• A session is a row on the server; the cookie holds its random token.
• Tokens must be long and random, never built from guessable parts.
• A signature made with a secret proves the server made a value; it does not hide it.
• A JWT carries its own facts; it is fast to check but hard to revoke.
• Sliding sessions keep active people signed in and forgotten devices out.
• Websites keep session tokens in HttpOnly cookies.

Databases leak: a stolen backup, a misconfigured server, an employee with too much access. If the notes app kept passwords as typed, a leak would hand out every password, and most people reuse theirs on other sites, including their email and bank.

The goal: the server must be able to check a password without being able to recover it. That is exactly what a hash gives.

A hash function turns any input into a fixed-length string of characters. The same input always gives the same output, a tiny change gives a completely different one, and there is no way to run it backwards.

1"correct horse"  ->  9b71d224bd62f378...2"correct horsf"  ->  a3c5e0b1f4829d06...3"correct horse"  ->  9b71d224bd62f378...   (same as the first)

Plain hashing has a flaw: everyone with the password sunshine1 gets the same hash, and attackers keep huge precomputed lists of common passwords and their hashes. A salt fixes this: a random value made for each user and mixed in before hashing, then stored next to the hash.

General hashes like SHA-256 are built to be fast: a graphics card can try billions of guesses a second. Password hashes such as scrypt, Argon2 and bcrypt are deliberately slow and memory-hungry, so each guess costs real time. A tenth of a second per sign-in is nothing for a person and crippling for an attacker.

• Length is what makes guessing hard. Four random words beat P@ssw0rd!.
• Refuse known-breached passwords: lists of millions of leaked passwords exist, and attackers try those first.
• Allow every character, spaces included, and let password managers paste.
• Cap the length at something generous: hashing a megabyte of text would let anyone slow your server down.
• Don't force regular changes: people respond with Spring2024, Summer2024…

• Store a hash, never the password, and never something reversible.
• A per-user random salt makes identical passwords hash differently.
• Use a slow password hash: scrypt (Better Auth's default), Argon2 or bcrypt.
• A pepper is an extra secret kept outside the database.
• Prefer long passwords, refuse breached ones, cap the length.
• Check in constant time and answer the same for unknown emails.

An attacker wants to act as someone else: read their notes, change their email, lock them out. They rarely break cryptography. They trick people, guess, reuse leaks, or ride on a session the victim already has. Knowing the common moves makes the defences in this course make sense.

An email says "Your notes will be deleted, sign in to keep them", with a link to notes-example.com-login.net. The page looks exactly like the real one. Whatever Ana types goes to the attacker. No server-side code can stop her typing it.

• Second factors make a stolen password insufficient on its own (Module 14).
• Passkeys cannot be phished at all: the browser only uses them on the real site.
• Never redirect to untrusted addresses: an app that forwards people anywhere after sign-in becomes a tool for phishing. Better Auth only redirects to origins you trust.
• Tell people about changes: an email on every password or email change warns the real owner.

A list of which emails have accounts helps phishing ("we noticed a problem with your notes account") and focuses guessing. On some apps, simply having an account is private. Module 9 shows the Better Auth settings that let sign-up give the same answer either way.

Cross-site request forgery uses the fact that browsers attach cookies on their own. If Ana, signed in, visits a hostile page, that page can try to make her browser send a request to the notes app. If the cookie goes along, the server thinks Ana asked.

• SameSite=Lax stops the browser attaching the cookie to cross-site posts.
• The server checks the request's Origin header against origins it trusts; Better Auth does this on its own endpoints.
• Requests that change things are never GETs, which links and images can trigger.

Cross-site scripting happens when text from a user is put into a page as HTML. If a note containing <script>…</script> is shown as HTML, the script runs for everyone who opens it, with all the power of the real page.

A session cookie can be stolen by malware on the computer, read from a careless log file, or left behind on a shared library computer. The thief does not need the password: the cookie is enough.

• Phishing steals passwords on fake pages: passkeys and second factors blunt it.
• Brute force hits one account; stuffing hits many once each: limit both ways.
• Never reveal which emails have accounts, in words or in timing.
• CSRF rides on cookies the browser sends by itself: SameSite and origin checks stop it.
• XSS runs a script on your page: show user text as text.
• A stolen session is as good as a password: expire, revoke, re-check.

Terminal

A window where you type commands instead of clicking.

Node.js

A program that runs JavaScript and TypeScript outside the browser: your server.

npm

The tool that downloads packages (code other people published) into your project.

Package

A library you install by name, such as better-auth or hono.

1mkdir notes-app && cd notes-app   # a folder for the project2npm init -y                       # a package.json describing it3npm install better-auth better-sqlite34npm install -D typescript tsx @types/better-sqlite3

Better Auth needs two settings. BETTER_AUTH_SECRET is a long random value it uses to sign cookies and links (Module 3). BETTER_AUTH_URL is the address your server is reached at. Both are environment variables: settings given to a program from outside its code, so secrets never sit in the code itself.

1# make a secret with:  openssl rand -base64 322BETTER_AUTH_SECRET=replace-with-your-own-random-value3BETTER_AUTH_URL=http://localhost:3000

A migration is a change to a database's structure, such as adding a table. Better Auth's command-line tool reads your auth.ts (plugins included) and either creates the tables directly or writes a schema file for your own migration tool.

1npx auth migrate     # create the tables in notes.db2npx auth generate    # or: write a schema file to review

An ORM is a library that lets code talk to the database in TypeScript instead of raw SQL. If your app uses Drizzle (or Prisma), give Better Auth an adapter for it. Its four tables then live in your own schema file, next to your notes table, and your usual migration tool creates them.

1import { betterAuth } from 'better-auth'2import {  } from 'better-auth/adapters/drizzle'3import { db } from './db'4import * as schema from './db/schema'5
6export const auth = betterAuth({7  database: drizzleAdapter(db, {8    provider: '',9    schema10  }),11  emailAndPassword: { enabled: true }12})

• npm install better-auth plus a database driver or adapter.
• BETTER_AUTH_SECRET and BETTER_AUTH_URL come from the environment; never commit them.
• betterAuth({ database, emailAndPassword }) in auth.ts is the whole configuration to start.
• Four tables: user, session, account, verification. Passwords live on the credential account.
• The command-line tool creates tables or writes a schema; rerun it after adding plugins.
• auth.handler serves HTTP; auth.api is for your own server code.

A server framework turns incoming requests into calls to your functions. Hono is a small, fast one that runs on Node.js and on edge platforms alike. You say "for GET /hello, run this", and it handles the rest. Each function gets c, the context: the request, and helpers to answer it.

1import { Hono } from 'hono'2import { serve } from '@hono/node-server'3
4const app = new Hono()5
6app.get('/hello', (c) => c.text('Hello from the notes app'))7
8serve({ fetch: app.fetch, port: 3000 })

Plugins add more under the same prefix. You rarely call these by hand: the client (Module 8) does it for you. But knowing they are plain HTTP makes them easy to test and debug.

Browsers add an Origin header to requests made by pages. Better Auth compares it with its trusted origins: its own baseURL plus any you list. Requests from other origins that carry cookies, and sign-ins or sign-ups from them, are refused, which stops CSRF (Module 5). The same list decides where it may redirect people after sign-in.

1export const auth = betterAuth({2  database: new Database('notes.db'),3  emailAndPassword: { enabled: true },4  trustedOrigins: ['https://notes.example.com']5})

If the pages live at https://notes.example.com and the server at https://api.notes.example.com, browsers block the pages from reading the server's answers unless the server allows it. That permission is CORS (cross-origin resource sharing), set with response headers.

1import { cors } from 'hono/cors'2
3app.use('/api/auth/*', cors({4  origin: 'https://notes.example.com',5  allowMethods: ['GET', 'POST', 'OPTIONS'],6  allowHeaders: ['Content-Type'],7  credentials: true8}))

• Mount auth.handler(c.req.raw) on GET and POST at /api/auth/*, matching basePath.
• Its endpoints are plain HTTP: sign-up, sign-in, sign-out, get-session and more.
• In your own routes, auth.api.getSession({ headers }) returns the user or null.
• Better Auth refuses requests from origins not in trustedOrigins.
• Pages on another origin need CORS with an exact origin and credentials: true.

Your pages could call fetch('/api/auth/sign-in/email', …) by hand. The client does it for you: a small object with a method per endpoint, typed, that handles cookies and errors the same way every time.

1import { createAuthClient } from 'better-auth/client'2
3export const authClient = createAuthClient({4  // only needed if the server is on another origin5  baseURL: 'https://api.notes.example.com'6})

Client calls do not throw when Better Auth refuses. They resolve to an object with two fields: data holds the answer when it worked, error describes the refusal when it did not, and the other one is null.

1const { data, error } = await authClient.signUp.email({2  name: 'Ana',3  email: 'ana@example.com',4  password: 'a long passphrase here'5})6
7if (error) {8  showMessage(error.message ?? 'Something went wrong')9} else {10  showMessage(`Welcome, ${data.user.name}`)11}

1try {2  await authClient.signIn.email({ email, password })3  location.href = '/notes'4} catch {5  showMessage('Wrong email or password')6}

• createAuthClient from better-auth/client, or better-auth/react for hooks.
• baseURL only when the server is on another origin.
• Calls return { data, error } and do not throw on refusals.
• signUp.email, signIn.email, signOut, getSession; the cookie is handled for you.
• useSession gives data and isPending and updates after sign-in and sign-out.
• Page checks are for convenience; the server enforces the rules.

With autoSignIn: false or requireEmailVerification: true, signing up with an email that already has an account does not fail. Better Auth hashes the password anyway (so it takes as long), answers as if it worked, and calls onExistingUserSignUp if you set it, so you can email the real owner.

1emailAndPassword: {2  enabled: true,3  requireEmailVerification: true,4  onExistingUserSignUp: async ({ user }) => {5    void sendEmail({6      to: user.email,7      subject: 'You already have a notes account',8      text: 'Someone tried to sign up with this email. '9        + 'If it was you, sign in or reset your password.'10    })11  }12}

1. Finds the user by email and the credential account.
2. Verifies the password against the stored hash; for unknown emails it still hashes, so timing says nothing.
3. With requireEmailVerification, refuses an unconfirmed email with 403 EMAIL_NOT_VERIFIED.
4. Creates a session row, recording the IP address and browser.
5. Sets the signed session cookie and returns the user.

On the server, auth.api calls throw an APIError (from better-auth/api) when Better Auth refuses, unless you pass asResponse: true, which hands the refusal back as a Response with its status instead. error.status is the reason as text ("UNAUTHORIZED"), error.statusCode the number, and error.body.code a stable code. Anything else thrown is a real failure, such as the database being down.

password.hash(password) returns the string to store; password.verify({ hash, password }) says whether they match. Both are async. Better Auth uses them for sign-up, sign-in, changes and resets. A common reason: moving users from an older system whose hashes you must still accept.

1import { hash, verify } from './argon2'2
3emailAndPassword: {4  enabled: true,5  password: {6    hash: (password) => hash(password),7    verify: ({ hash: stored, password }) =>8      verify(stored, password)9  }10}

• Tune lengths, autoSignIn and requireEmailVerification under emailAndPassword.
• Sign-up makes a user and a credential account; emails are lowercased.
• With autoSignIn off or verification required, existing emails get the same answer.
• Server calls throw APIError on refusal: handle that, rethrow everything else.
• Custom hash and verify let you use Argon2 or accept old hashes.
• changePassword needs the current password; revokeOtherSessions signs others out.

Typing an email proves nothing: anyone can type anyone's address. Opening a link that was sent to that address proves you can read its inbox. Three journeys rely on this.

Verification token

The secret part of an emailed link that proves it came from you.

Magic link

A link that signs you in without a password.

With requireEmailVerification: true, sign-in refuses unconfirmed emails, and emailVerification.sendOnSignIn: true sends a fresh link when they try. The alternative is to let people in but keep what depends on the email locked until it is confirmed.

• verification: { storeIdentifier: 'hashed' } keeps reset tokens only as hashes, so a database copy cannot reset anyone's password. The magic link plugin has storeToken: 'hashed'.
• Pages that receive tokens should send Referrer-Policy: no-referrer, so the token does not travel to other sites in the Referer header.
• Remove the token from the address bar once read, with history.replaceState.
• Keep lifetimes short, and send at most a few emails per address per hour.

• Links prove inbox access: verification, reset and magic links.
• emailVerification.sendVerificationEmail gets { user, url, token }; sendOnSignUp sends it at once.
• Send without making the reply wait, or timing reveals who has an account.
• Grant nothing because of an email until emailVerified is true.
• requestPasswordReset then resetPassword; revoke sessions and tell the owner.
• Magic links come from the magicLink plugin; store tokens hashed and keep them short-lived.

When a session is extended, the cookie must be extended too, or the browser drops it at its old Max-Age. Through the handler this is automatic. When your own route calls auth.api, ask for the headers and copy the Set-Cookie onto your reply.

1const { headers, response: session } =2  await auth.api.getSession({3    headers: c.req.raw.headers,4    returnHeaders: true5  })6for (const cookie of headers.getSetCookie())7  c.header('Set-Cookie', cookie, { append: true })

A session can be weeks old, and the person at the keyboard might not be its owner. session.freshAge (default 1 day) marks a session as fresh for that long after it was created. Some endpoints require a fresh session: listSessions and unlinkAccount answer 403 SESSION_NOT_FRESH otherwise, and deleting the account without a password answers SESSION_EXPIRED.

1Set-Cookie: __Secure-better-auth.session_token=…;2  Max-Age=604800; Path=/; HttpOnly; Secure; SameSite=Lax

• HttpOnly, SameSite=Lax and Path=/ are always the defaults.
• Secure and the __Secure- prefix are added when the base URL is HTTPS (or advanced.useSecureCookies says so). Browsers refuse a __Secure- cookie that isn't Secure.
• advanced.cookiePrefix changes better-auth to your own name; advanced.defaultCookieAttributes changes attributes for every cookie.

Every getSession reads the database. With session.cookieCache: { enabled: true, maxAge: 300 }, Better Auth also sets a signed session_data cookie holding the session itself, and trusts it for up to maxAge seconds without a lookup.

• getSession checks the signature, the row and the expiry, and extends sessions older than updateAge.
• expiresIn 7 days and updateAge 1 day by default, in seconds.
• Pass refreshed Set-Cookie headers on when calling auth.api yourself.
• Dangerous actions want a fresh session or the password.
• listSessions, revokeSession, revokeOtherSessions, revokeSessions make a devices page.
• Cookies are HttpOnly, SameSite=Lax, and Secure with __Secure- on HTTPS.
• The cookie cache skips lookups but delays revocation by up to maxAge.

With "Sign in with GitHub", Ana proves who she is to GitHub, and GitHub tells the notes app, through a short exchange the app can verify. The notes app never sees her GitHub password. OAuth 2.0 is the name of that exchange. OpenID Connect is a layer on top that adds a signed statement of who signed in, used by Google and others.

Think of a hotel guest letting a friend into their room: instead of handing over their own key, they ask the front desk to issue a limited key card. OAuth issues the app a limited permission, never the password itself.

Provider

The service that vouches: GitHub, Google, Apple…

Client id and client secret

Your app's identity at the provider. The id is public; the secret stays on your server.

Redirect URI

Where the provider sends the browser back. Registered in advance; must match exactly.

Scope

What you ask to see: user:email at GitHub, openid email profile at Google.

Authorization code

A one-time code in the redirect, worth nothing until your server exchanges it.

Access token

What the exchange returns: permission to call the provider's API for that user.

1. In GitHub's developer settings, create an OAuth app.
2. Set its callback URL to http://localhost:3000/api/auth/callback/github for development; production gets its own app or URL.
3. Copy the client id, and generate a client secret.
4. Do the same for Google in its cloud console, with /api/auth/callback/google.

1GITHUB_CLIENT_ID=from-github-developer-settings2GITHUB_CLIENT_SECRET=from-github-developer-settings3GOOGLE_CLIENT_ID=from-google-cloud-console4GOOGLE_CLIENT_SECRET=from-google-cloud-console

• State is a random value sent out and expected back. It stops login CSRF: an attacker sending your browser to the callback with their code, so you end up signed in as them and type your notes into their account.
• PKCE (said "pixie") is a secret verifier: only its hash goes out at the start, the verifier itself only at the exchange. A stolen code is useless without it.

Ana signed up with a password. Months later she clicks "Sign in with Google" with the same email. Better Auth can link the Google account to her existing user instead of failing. It does so only when the provider says the email is verified (or is listed in accountLinking.trustedProviders) and, by default, when the local email is verified too.

1// on the settings page, signed in already2await authClient.linkSocial({3  provider: 'github',4  callbackURL: '/settings'5})6const { data: accounts } = await authClient.listAccounts()7const github = accounts?.find((a) => a.providerId === 'github')8if (github) await authClient.unlinkAccount({ accountId: github.id })

• Linking runs the same OAuth flow, then attaches the account to the signed-in user.
• By default the provider's email must match the user's; allowDifferentEmails changes that, at a risk.
• Unlinking needs a fresh session (Module 11), and unlinking the last way in is refused unless allowUnlinkingAll is on, so nobody locks themselves out.
• disableImplicitLinking turns off linking at sign-in, leaving only this explicit way.

• OAuth: redirect to the provider, code back, server-side exchange, profile, session.
• Register the app; the redirect URI is /api/auth/callback/<provider>.
• socialProviders with secrets from the environment; signIn.social starts it.
• State ties the callback to the browser; PKCE makes a stolen code useless.
• Accounts are found by provider and the provider's id, not by email.
• Implicit linking needs a verified email on both sides; linkSocial links on purpose.

A middleware is a function that runs before your route handlers. Instead of calling getSession in every route, one middleware does it and stores the result on c, Hono's context, where every handler can read it.

1type Session = typeof auth.$Infer.Session2
3type AppEnv = {4  Variables: {5    user: Session['user'] | null6    session: Session['session'] | null7  }8}9const app = new Hono<AppEnv>()10
11app.use('*', async (c, next) => {12  const found = await auth.api.getSession({13    headers: c.req.raw.headers14  })15  c.set('user', found?.user ?? null)16  c.set('session', found?.session ?? null)17  await next()18})

A signed-in person can send any id in a URL. If the handler finds a note by id alone, anyone can read anyone's notes. This hole has a name: an insecure direct object reference (IDOR). Put the owner into the query itself.

const note = await db.query.notes  .findFirst({    where: eq(notes.id, id)  })